Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FONTCONFIG(3)		   Library Functions Manual		 FONTCONFIG(3)

NAME
       fontconfig - Font configuration and customization library

SYNOPSIS
       #include	<fontconfig/fontconfig.h>
       #include	<fontconfig/fcfreetype.h>

DESCRIPTION
       Fontconfig is a library designed	to provide system-wide font configura-
       tion, customization and application access.

FUNCTIONAL OVERVIEW
       Fontconfig contains two essential  modules,  the	 configuration	module
       which  builds an	internal configuration from XML	files and the matching
       module which accepts font patterns and  returns	the  nearest  matching
       font.

   FONT	CONFIGURATION
       The  configuration  module  consists of the FcConfig datatype, libexpat
       and FcConfigParse which walks over an XML tree and ammends a configura-
       tion  with data found within.  From an external perspective, configura-
       tion of the library consists of generating a valid XML tree and feeding
       that  to	 FcConfigParse.	 The only other	mechanism provided to applica-
       tions for changing the running configuration is to add fonts and	direc-
       tories to the list of application-provided font files.

       The intent is to	make font configurations relatively static, and	shared
       by as many applications as possible.  It	is hoped that this  will  lead
       to  more	 stable	font selection when passing names from one application
       to another.  XML	was chosen as a	configuration file format  because  it
       provides	 a  format which is easy for external agents to	edit while re-
       taining the correct structure and syntax.

       Font configuration is separate from font	matching; applications needing
       to  do  their  own matching can access the available fonts from the li-
       brary and perform private matching.  The	intent is to  permit  applica-
       tions to	pick and choose	appropriate functionality from the library in-
       stead of	forcing	them to	choose between this library and	a private con-
       figuration  mechanism.  The hope	is that	this will ensure that configu-
       ration of fonts for all applications can	be centralized in  one	place.
       Centralizing  font configuration	will make simplify and regularize font
       installation and	customization.

   FONT	PROPERTIES
       While font patterns may contain essentially any properties,  there  are
       some well known properties with associated types.  Fontconfig uses some
       of these	properties for font matching and font completion.  Others  are
       provided	as a convenience for the applications rendering	mechanism.

       Property	 CPP symbol	  Type	  Description
       ---------- --------------------------------------------
       family	 FC_FAMILY	  String  Font family name
       style	 FC_STYLE	  String  Font style. Overrides	weight and slant
       slant	 FC_SLANT	  Int	  Italic, oblique or roman
       weight	 FC_WEIGHT	  Int	  Light, medium, demibold, bold	or black
       size	 FC_SIZE	  Double  Point	size
       aspect	 FC_ASPECT	  Double  Stretches glyphs horizontally	before hinting
       pixelsize FC_PIXEL_SIZE	  Double  Pixel	size
       spacing	 FC_SPACING	  Int	  Proportional,	monospace or charcell
       foundry	 FC_FOUNDRY	  String  Font foundry name
       antialias FC_ANTIALIAS	  Bool	  Whether glyphs can be	antialiased
       hinting	 FC_HINTING	  Bool	  Whether the rasterizer should	use hinting
       verticallayout		  FC_VERTICAL_LAYOUT	      BoolUse vertical layout
       autohint	 FC_AUTOHINT	  Bool	  Use autohinter instead of normal hinter
       globaladvance		  FC_GLOBAL_ADVANCE	      BoolUse font global advance data
       file	 FC_FILE	  String  The filename holding the font
       index	 FC_INDEX	  Int	  The index of the font	within the file
       ftface	 FC_FT_FACE	  FT_Face Use the specified FreeType face object
       rasterizer		  FC_RASTERIZER		      StringWhich rasterizer is	in use
       outline	 FC_OUTLINE	  Bool	  Whether the glyphs are outlines
       scalable	 FC_SCALABLE	  Bool	  Whether glyphs can be	scaled
       scale	 FC_SCALE	  Double  Scale	factor for point->pixel	conversions
       dpi	 FC_DPI		  Double  Target dots per inch
       rgba	 FC_RGBA	  Int	  unknown, rgb,	bgr, vrgb, vbgr, none -	subpixel geometry
       minspace	 FC_MINSPACE	  Bool	  Eliminate leading from line spacing
       charset	 FC_CHARSET	  CharSet Unicode chars	encoded	by the font
       lang	 FC_LANG	  String  List of RFC-3066-style languages this	font supports

   FONT	MATCHING
       Fontconfig  performs matching by	measuring the distance from a provided
       pattern to all of the available	fonts  in  the	system.	  The  closest
       matching	font is	selected.  This	ensures	that a font will always	be re-
       turned, but doesn't ensure that it is anything like the requested  pat-
       tern.

       Font  matching starts with an application constructed pattern.  The de-
       sired attributes	of the resulting font are collected together in	an Fc-
       Pattern	object.	  Each property	of the pattern can contain one or more
       values; these are listed	in priority order; matches earlier in the list
       are considered "closer" than matches later in the list.

       The  initial  pattern  is  modified by applying the list	of editing in-
       structions specific to patterns found in	the configuration;  each  con-
       sists  of  a match predicate and	a set of editing operations.  They are
       executed	in the order they appeared in the configuration.   Each	 match
       causes the associated sequence of editing operations to be applied.

       After  the pattern has been edited, a sequence of default substitutions
       are performed to	canonicalize the set  of  available  properties;  this
       avoids the need for the lower layers to constantly provide default val-
       ues for various font properties during rendering.

       The canonical font pattern is finally  matched  against	all  available
       fonts.	The distance from the pattern to the font is measured for each
       of several properties: foundry, charset,	family,	lang, spacing,	pixel-
       size,  style,  slant,  weight, antialias, rasterizer and	outline.  This
       list is in priority order -- results of comparing earlier  elements  of
       this list weigh more heavily than later elements.

       There is	one special case to this rule; family names are	split into two
       bindings; strong	and weak.   Strong  family  names  are	given  greater
       precedence  in the match	than lang elements while weak family names are
       given lower precedence than lang	elements.  This	permits	 the  document
       language	 to  drive  font selection when	any document specified font is
       unavailable.

       The pattern representing	that font is augmented to include any  proper-
       ties  found  in the pattern but not found in the	font itself; this per-
       mits the	application to pass rendering instructions or any  other  data
       through the matching system.  Finally, the list of editing instructions
       specific	to fonts found in the configuration are	applied	 to  the  pat-
       tern.  This modified pattern is returned	to the application.

       The  return value contains sufficient information to locate and raster-
       ize the font, including the file	name, pixel size and  other  rendering
       data.  As none of the information involved pertains to the FreeType li-
       brary, applications are free to use any rasterization engine or even to
       take the	identified font	file and access	it directly.

       The  match/edit	sequences  in  the  configuration are performed	in two
       passes because there are	essentially two	different operations necessary
       -- the first is to modify how fonts are selected; aliasing families and
       adding suitable defaults.  The second is	to  modify  how	 the  selected
       fonts  are  rasterized.	Those must apply to the	selected font, not the
       original	pattern	as false matches will often occur.

   FONT	LIST MATCHING
       While many applications want to locate  a  single  font	best  matching
       their  search criteria, other applications need to build	a set of fonts
       which can be used to present any	Unicode	data.  Fontconfig provides  an
       API  to generate	a list sorted by the nearness of each font to the pat-
       tern.  Every font in the	system is considered, the best matching	 fonts
       are  placed first.  The application then	can select whether the remain-
       ing fonts are unconditionally included in the list, or whether they are
       included	 only  if they cover portions of Unicode not covered by	any of
       the preceeding fonts.

       The list	resulting from this match is represented by references to  the
       original	 font  patterns	 and  so consumes very little memory.  Using a
       list entry involves creating a pattern which combines  the  information
       from  the  font with the	information from the original pattern and exe-
       cuting the font substitutions.

   FONT	NAMES
       Fontconfig provides a textual representation for	patterns that the  li-
       brary  can  both	 accept	 and generate.	The representation is in three
       parts, first a list of family names, second a list of point  sizes  and
       finally a list of additional properties:
	    <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...
       Values  in  a list are separated	with commas.  The name needn't include
       either families or point	sizes; they can	be elided.  In addition, there
       are  symbolic  constants	that simultaneously indicate both a name and a
       value.  Here are	some examples:

		 Times-12	     12	point Times Roman
		 Times-12:bold	     12	point Times Bold
		 Courier:italic	     Courier Italic in the default size
		 Monospace:matrix=1 .1 0 1The users preferred monospace	font
				     with artificial obliquing

LANG TAGS
       Each font in the	database contains a list  of  languages	 it  supports.
       This is computed	by comparing the Unicode coverage of the font with the
       orthography of each language.  Languages	are tagged using  an  RFC-3066
       compatible  naming  and	occur  in two parts -- the ISO639 language tag
       followed	a hyphen and then by the ISO 3166 country  code.   The	hyphen
       and country code	may be elided.

       Fontconfig  has	orthographies for several languages built into the li-
       brary.  No provision has	been made for adding new ones aside  from  re-
       building	 the  library.	It currently supports 122 of the 139 languages
       named in	ISO 639-1, 141 of the languages	with two-letter	codes from ISO
       639-2 and another 30 languages with only	three-letter codes.

DATATYPES
       FcChar8
       FcChar16
       FcChar32
       FcBool These  are primitive datatypes; the FcChar* types	hold precisely
	      the number of bits stated	(if supported  by  the	C  implementa-
	      tion).  FcBool holds one of two CPP symbols: FcFalse or FcTrue.

       FcMatrix
	      An  FcMatrix holds an affine transformation, usually used	to re-
	      shape glyphs.  A small set of matrix operations are provided  to
	      manipulate these.

		   typedef struct _FcMatrix {
			double xx, xy, yx, yy;
		   } FcMatrix;

       FcCharSet
	      An  FcCharSet  is	an abstract type that holds the	set of encoded
	      unicode chars in a font.	Operations to build and	compare	 these
	      sets are provided.

       FcType Tags the kind of data stored in an FcValue.

       FcValue
	      An  FcValue  object holds	a single value with one	of a number of
	      different	types.	The  'type'  tag  indicates  which  member  is
	      valid.

		   typedef struct _FcValue {
			FcType type;
			union {
			     const FcChar8 *s;
			     int i;
			     FcBool b;
			     double d;
			     const FcMatrix *m;
			     const FcCharSet *c;
			} u;
		   } FcValue;

		 type	   Union member	       Datatype
		 ------------------------------
		 FcTypeVoid	     (none)    (none)
		 FcTypeInteger	     i	       int
		 FcTypeDouble	     d	       double
		 FcTypeString	     s	       char *
		 FcTypeBool	     b	       b
		 FcTypeMatrix	     m	       FcMatrix	*
		 FcTypeCharSet	     c	       FcCharSet *

       FcPattern
	      holds  a	set  of	 names	with associated	value lists; each name
	      refers to	a property of a	font.  FcPatterns are used  as	inputs
	      to  the  matching	code as	well as	holding	information about spe-
	      cific fonts.  Each property can hold one or more values; conven-
	      tionally	all  of	 the same type,	although the interface doesn't
	      demand that.

       FcFontSet

		   typedef struct _FcFontSet {
			int nfont;
			int sfont;
			FcPattern **fonts;
		   } FcFontSet;
	      An FcFontSet contains a list of FcPatterns.  Internally fontcon-
	      fig uses this data structure to hold sets	of fonts.  Externally,
	      fontconfig returns the results of	listing	fonts in this  format.
	      'nfont'  holds  the  number  of  patterns	 in the	'fonts'	array;
	      'sfont' is used to indicate the size of that array.

       FcStrSet
	      FcStrList	FcStrSet holds a list of strings that can be  appended
	      to  and  enumerated.  Its	unique characteristic is that the enu-
	      meration works even while	strings	are appended  during  enumera-
	      tion.   FcStrList	 is used during	enumeration to safely and cor-
	      rectly walk the list of strings even while that list  is	edited
	      in the middle of enumeration.

       FcObjectSet

		   typedef struct _FcObjectSet {
			int nobject;
			int sobject;
			const char **objects;
		   } FcObjectSet;

	      holds  a	set  of	names and is used to specify which fields from
	      fonts are	placed in the the list of returned patterns when list-
	      ing fonts.

       FcObjectType

		   typedef  struct  _FcObjectType  {	       const char *ob-
	      ject;	      FcType type;	} FcObjectType;
	      marks the	type of	a pattern element generated when parsing  font
	      names.  Applications can add new object types so that font names
	      may contain the new elements.

       FcConstant

		   typedef struct _FcConstant {		 const FcChar8	*name;
			const  char  *object;		 int value;	 } Fc-
	      Constant;
	      Provides for symbolic constants for new pattern elements.	  When
	      'name'  is  seen	in a font name,	an 'object' element is created
	      with value 'value'.

       FcBlanks
	      holds a list of Unicode chars which are expected	to  be	blank;
	      unexpectedly  blank  chars  are  assumed	to  be invalid and are
	      elided from the charset associated with the font.

       FcFileCache
	      holds the	per-user cache information for use while  loading  the
	      font  database. This is built automatically for the current con-
	      figuration when that is loaded.  Applications must  always  pass
	      '0' when one is requested.

       FcConfig
	      holds  a complete	configuration of the library; there is one de-
	      fault configuration, other can  be  constructed  from  XML  data
	      structures.   All	 public	entry points that need global data can
	      take an optional FcConfig* argument; passing 0 uses the  default
	      configuration.   FcConfig	 objects  hold	two sets of fonts, the
	      first contains those specified by	the configuration, the	second
	      set  holds  those	 added by the application at run-time.	Inter-
	      faces that need to reference a particulat	set use	one of the Fc-
	      SetName enumerated values.

       FcSetName
	      Specifies	one of the two sets of fonts available in a configura-
	      tion; FcSetSystem	for those fonts	specified in the configuration
	      and  FcSetApplication which holds	fonts provided by the applica-
	      tion.

       FcResult
	      Used as a	return type for	functions manipulating	FcPattern  ob-
	      jects.

		 Result	code	     Meaning
		 ------------------------------
		 FcResultMatch	     Object exists with	the specified ID
		 FcResultNoMatch     Object doesn't exist at all
		 FcResultTypeMismatch	       Object  exists,	but  the  type
       doesn't match
		 FcResultNoId	     Object exists, but	has fewer values  than
       specified

       FcAtomic
	      Used for locking access to config	files.	Provides a safe	way to
	      update configuration files.

FUNCTIONS
   FcMatrix
       FcMatrix	structures hold	an affine transformation in matrix form.

       Initializes a matrix to the identify transformation.

       FcMatrix	*FcMatrixCopy (const FcMatrix *mat)
	      Allocates	a new FcMatrix and copies 'mat'	into it.

       FcBool FcMatrixEqual (const FcMatrix *mat1, const FcMatrix *mat2)
	      Returns FcTrue if	'mat1' and 'mat2' are equal, else FcFalse.

       void FcMatrixMultiply (FcMatrix *result,	const FcMatrix *a, const FcMa-
       trix *b)
	      Multiplies 'a' and 'b' together, placing the result in 'result'.
	      'result' may refer to the	sam matrix as either 'a' or 'b'.

       void FcMatrixRotate (FcMatrix *m, double	c, double s)
	      If 'c' is	cos(angle) and 's' is sin(angle),  FcMatrixRotate  ro-
	      tates the	matrix by 'angle'.

       void FcMatrixScale (FcMatrix *m,	double sx, double sy)
	      Scales  'm'  by 'sx' in the horizontal dimension and 'sy'	in the
	      vertical dimension.

       void FcMatrixShear (FcMatrix *m,	double sh, double sv)
	      Shears 'm' by 'sh' in the	horizontal direction and 'sv'  in  the
	      vertical direction.

   FcCharSet
       An  FcCharSet  is  a  boolean  array indicating a set of	unicode	chars.
       Those associated	with a font are	marked constant	and cannot be  edited.
       FcCharSets  may	be  reference counted internally to reduce memory con-
       sumption; this may be visible to	applications as	the result  of	FcCha-
       rSetCopy	 may return it's argument, and that CharSet may	remain unmodi-
       fiable.

       FcCharSet *FcCharSetCreate (void)
	      Creates an empty FcCharSet object.

       void FcCharSetDestroy (FcCharSet	*fcs)
	      Frees an FcCharSet object.

       FcBool FcCharSetAddChar (FcCharSet *fcs,	FcChar32 ucs4)
	      Adds a single unicode char to  the  set,	returning  FcFalse  on
	      failure,	either	as  a result of	a constant set or from running
	      out of memory.

       FcCharSet *FcCharSetCopy	(FcCharSet *src)
	      Makes a copy of 'src'; note that this may	not actually  do  any-
	      thing more than increment	the reference count on 'src'.

       FcBool FcCharSetEqual (const FcCharSet *a, const	FcCharSet *b)
	      Returns  whether	'a'  and  'b'  contain the same	set of unicode
	      chars.

       FcCharSet *FcCharSetIntersect (const FcCharSet *a, const	FcCharSet *b)
	      Returns a	set including only those chars found in	both  'a'  and
	      'b'.

       FcCharSet *FcCharSetUnion (const	FcCharSet *a, const FcCharSet *b);
	      Returns  a set including only those chars	found in either	'a' or
	      'b'.

       FcCharSet *FcCharSetSubtract (const FcCharSet *a, const FcCharSet *b)
	      Returns a	set including only those chars found in	 'a'  but  not
	      'b'.

       FcBool FcCharSetHasChar (const FcCharSet	*fcs, FcChar32 ucs4)
	      Returns whether 'fcs' contains the char 'ucs4'.

       FcChar32	FcCharSetCount (const FcCharSet	*a)
	      Returns the total	number of unicode chars	in 'a'.

       FcChar32	 FcCharSetIntersectCount  (const FcCharSet *a, const FcCharSet
       *b)
	      Returns the number of chars that are in both 'a' and 'b'.

       FcChar32	FcCharSetSubtractCount (const FcCharSet	 *a,  const  FcCharSet
       *b)
	      Returns the number of chars that are in 'a' but not in 'b'.

       FcBool FcCharSetIsSubset	(const FcCharSet *a, const FcCharSet *b)
	      Returns whether 'a' is a subset of 'b'.

       FcChar32	   FcCharSetFirstPage	 (const	   FcCharSet	*a,   FcChar32
       [FC_CHARSET_MAP_SIZE], FcChar32 *next)
	      Builds an	array of bits marking the first	page of	Unicode	cover-
	      age of 'a'.  Returns the base of the array.  'next' contains the
	      next page	in the font.

       FcChar32	   FcCharSetNextPage	(const	  FcCharSet    *a,    FcChar32
       [FC_CHARSET_MAP_SIZE], FcChar32 *next)
	      Builds  an array of bits marking the Unicode coverage of 'a' for
	      page '*next'.  Returns the base of the array.   'next'  contains
	      the next page in the font.

   FcValue
       FcValue	is a structure containing a type tag and a union of all	possi-
       ble datatypes.  The tag is an enum of type FcType and  is  intended  to
       provide	a  measure  of run-time	typechecking, although that depends on
       careful programming.

       void FcValueDestroy (FcValue v)
	      Frees any	memory referenced by  `v'.   Values  of	 type  FcType-
	      String,  FcTypeMatrix  and  FcTypeCharSet	 reference memory, the
	      other types do not.

       FcValue FcValueSave (FcValue v)
	      Returns a	copy of	`v' duplicating	any object referenced by it so
	      that `v' may be safely destroyed without harming the new value.

   FcPattern
       An  FcPattern  is  an  opaque  type  that  holds	both patterns to match
       against the available fonts, as well  as	 the  information  about  each
       font.

       FcPattern *FcPatternCreate (void)
	      Creates  a  pattern  with	 no properties;	used to	build patterns
	      from scratch.

       void FcPatternDestroy (FcPattern	*p)
	      Destroys a pattern, in the process destroying all	 related  val-
	      ues.

       FcBool FcPatternEqual (const FcPattern *pa, const FcPattern *pb);
	      Returns whether 'pa' and 'pb' are	exactly	alike.

       FcBool  FcPatternEqualSubset (const FcPattern *pa, const	FcPattern *pb,
       const FcObjectSet *os)
	      Returns whether 'pa' and 'pb' have exactly the same  values  for
	      all of the objects in 'os'.

       FcChar32	FcPatternHash (const FcPattern *p)
	      Returns  a  32-bit number	which is the same for any two patterns
	      which are	exactly	alike.

       FcBool FcPatternAdd (FcPattern *p, const	char *object,  FcValue	value,
       FcBool append)
	      Adds  a  single  value to	the list of values associated with the
	      property named `object'.	If `append' is FcTrue,	the  value  is
	      added  at	the end	of any existing	list, otherwise	it is inserted
	      at the begining.	`value'	is saved (with FcValueSave)  when  in-
	      serted into the pattern so that the library retains no reference
	      to any application-supplied data structure.

       FcBool FcPatternAddWeak (FcPattern  *p,	const  char  *object,  FcValue
       value, FcBool append)
	      FcPatternAddWeak	is essentially the same	as FcPatternAdd	except
	      that any values added to the list	have binding 'weak' instead of
	      'strong'.

       FcBool FcPatternAddInteger (FcPattern *p, const char *object, int i)
       FcBool FcPatternAddDouble (FcPattern *p,	const char *object, double d)
       FcBool FcPatternAddString (FcPattern *p,	const char *object, const char
       *s)
       FcBool FcPatternAddMatrix (FcPattern *p,	const char *object, const  Fc-
       Matrix *s)
       FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const Fc-
       CharSet *c)
       FcBool FcPatternAddBool (FcPattern *p, const char *object, FcBool b)
	      These are	all convenience	functions that insert objects  of  the
	      specified	type into the pattern.	Use these in preference	to Fc-
	      PatternAdd  as  they  will  provide  compile-time	 typechecking.
	      These all	append values to any existing list of values.

       FcResult	 FcPatternGet  (FcPattern  *p, const char *object, int id, Fc-
       Value *v)
	      Returns in `v' the `id'th	value  associated  with	 the  property
	      `object'.	  The  value returned is not a copy, but rather	refers
	      to the data stored within	the  pattern  directly.	  Applications
	      must not free this value.

       FcResult	 FcPatternGetInteger (FcPattern	*p, const char *object,	int n,
       int *i);
       FcResult	FcPatternGetDouble (FcPattern *p, const	char *object,  int  n,
       double *d);
       FcResult	 FcPatternGetString  (FcPattern	*p, const char *object,	int n,
       char **const s);
       FcResult	FcPatternGetMatrix (FcPattern *p, const	char *object,  int  n,
       FcMatrix	**s);
       FcResult	 FcPatternGetCharSet (FcPattern	*p, const char *object,	int n,
       FcCharSet **c);
       FcResult	FcPatternGetBool (FcPattern *p,	const char *object, int	n, Fc-
       Bool *b);
	      These  are convenience functions that call FcPatternGet and ver-
	      ify that the returned data is of the expected type. They	return
	      FcResultTypeMismatch  if	this is	not the	case.  Note that these
	      (like FcPatternGet) do not make a	copy  of  any  data  structure
	      referenced  by the return	value.	Use these in preference	to Fc-
	      PatternGet to provide compile-time typechecking.

       FcPattern *FcPatternBuild (FcPattern *orig, ...);
       FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va)
	      Builds a pattern using a list  of	 objects,  types  and  values.
	      Each  value to be	entered	in the pattern is specified with three
	      arguments:

	      1. Object	name, a	string describing the property to be added.

	      2. Object	type, one of the FcType	enumerated values

	      3. Value,	not an FcValue,	but the	raw type as passed to  any  of
	      the  FcPatternAdd<type>  functions.   Must match the type	of the
	      second argument.

	      The argument list	is terminated by a null	object name, no	object
	      type nor value need be passed for	this.  The values are added to
	      `pattern', if `pattern' is null, a new pattern is	 created.   In
	      either case, the pattern is returned. Example:

		     pattern  =	 FcPatternBuild	 (0,  FC_FAMILY, FtTypeString,
		     "Times", (char *) 0);

	      FcPatternVaBuild is used when the	arguments are already  in  the
	      form of a	varargs	value.

       FcBool FcPatternDel (FcPattern *p, const	char *object)
	      Deletes  all  values  associated with the	property `object', re-
	      turning whether the property existed or not.

       void FcPatternPrint (const FcPattern *p)
	      Prints an	easily readable	version	 of  the  pattern  to  stdout.
	      There  is	 no  provision for reparsing data in this format, it's
	      just for diagnostics and debugging.

       void FcDefaultSubstitute	(FcPattern *pattern)
	      Supplies default values for underspecified font patterns:

	      o	     Patterns without a	specified style	or weight are  set  to
		     Medium

	      o	     Patterns  without	a  specified style or slant are	set to
		     Roman

	      o	     Patterns without a	specified pixel	 size  are  given  one
		     computed  from any	specified point	size (default 12), dpi
		     (default 75) and scale (default 1).

       FcPattern *FcNameParse (const char *name)
	      Converts 'name' from the standard	text  format  described	 above
	      into a pattern.

       FcChar8 *FcNameUnparse (FcPattern *pat)
	      Converts	the  given  pattern  into the standard text format de-
	      scribed above.  The return value	is  not	 static,  but  instead
	      refers  to  newly	 allocated memory which	should be freed	by the
	      caller.

   FcFontSet
       An FcFontSet simply holds a list	of patterns; these are used to	return
       the results of listing available	fonts.

       FcFontSet *FcFontSetCreate (void)
	      Creates an empty font set.

       void FcFontSetDestroy (FcFontSet	*s);
	      Destroys	a  font	 set.	Note that this destroys	any referenced
	      patterns as well.

       FcBool FcFontSetAdd (FcFontSet *s, FcPattern *font)
	      Adds a pattern to	a font set.  Note  that	 the  pattern  is  not
	      copied before being inserted into	the set.

   FcObjectSet
       An  FcObjectSet	holds  a list of pattern property names; it is used to
       indiciate which properties are to be returned in	the patterns from  Fc-
       FontList.

       FcObjectSet *FcObjectSetCreate (void)
	      Creates an empty set.

       FcBool FcObjectSetAdd (FcObjectSet *os, const char *object)
	      Adds a proprety name to the set.

       void FcObjectSetDestroy (FcObjectSet *os)
	      Destroys an object set.

       FcObjectSet *FcObjectSetBuild (const char *first, ...)
       FcObjectSet *FcObjectSetVaBuild (const char *first, va_list va)
	      These  build  an object set from a null-terminated list of prop-
	      erty names.

   FcObjectType
       Provides	for applcation-specified font name object types	 so  that  new
       pattern elements	can be generated from font names.

       FcBool FcNameRegisterObjectTypes	(const FcObjectType *types, int	ntype)
	      Register 'ntype' new object types.

       FcBool  FcNameUnregisterObjectTypes  (const  FcObjectType  *types,  int
       ntype)
	      Unregister 'ntype' object	types.

       const FcObjectType *FcNameGetObjectType (const char *object)
	      Return the object	type for the pattern element named 'object'.

   FcConstant
       Provides	for application-specified symbolic constants for font names.

       FcBool FcNameRegisterConstants (const FcConstant	*consts, int nconsts)
	      Register 'nconsts' new symbolic constants.

       FcBool FcNameUnregisterConstants	(const FcConstant *consts,  int	 ncon-
       sts)
	      Unregister 'nconsts' symbolic constants.

       const FcConstant	*FcNameGetConstant (FcChar8 *string)
	      Return  the  FcConstant  structure  related to symbolic constant
	      'string'.

       FcBool FcNameConstant (FcChar8 *string, int *result);
	      Returns whether a	symbolic constant with name 'string' is	regis-
	      tered, placing the value of the constant in 'result' if present.

   FcBlanks
       An  FcBlanks object holds a list	of Unicode chars which are expected to
       be blank	when drawn.  When scanning new fonts,  any  glyphs  which  are
       empty  and not in this list will	be assumed to be broken	and not	placed
       in the FcCharSet	associated with	the font.  This	 provides  a  signifi-
       cantly more accurate CharSet for	applications.

       FcBlanks	*FcBlanksCreate	(void)
	      Creates an empty FcBlanks	object.

       void FcBlanksDestroy (FcBlanks *b)
	      Destroys an FcBlanks object, freeing any associated memory.

       FcBool FcBlanksAdd (FcBlanks *b,	FcChar32 ucs4)
	      Adds a single character to an FcBlanks object, returning FcFalse
	      if this process ran out of memory.

       FcBool FcBlanksIsMember (FcBlanks *b, FcChar32 ucs4)
	      Returns whether the specified FcBlanks object contains the indi-
	      cated Unicode value.

   FcConfig
       An  FcConfig  object  holds the internal	representation of a configura-
       tion.  There is a default configuration which applications may  use  by
       passing 0 to any	function using the data	within an FcConfig.

       FcConfig	*FcConfigCreate	(void)
	      Creates an empty configuration.

       void FcConfigDestroy (FcConfig *config)
	      Destroys	a configuration	and any	data associated	with it.  Note
	      that calling this	function with the return from  FcConfigGetCur-
	      rent will	place the library in an	indeterminate state.

       FcBool FcConfigSetCurrent (FcConfig *config)
	      Sets  the	current	default	configuration to 'config'.  Implicitly
	      calls FcConfigBuildFonts if necessary, returning FcFalse if that
	      call fails.

       FcConfig	*FcConfigGetCurrent (void)
	      Returns the current default configuration.

       FcBool FcConfigUptoDate (FcConfig *config)
	      Checks  all of the files related to 'config' and returns whether
	      the in-memory version is in sync with the	disk version.

       FcBool FcConfigBuildFonts (FcConfig *config)
	      Builds the set of	available fonts	for the	 given	configuration.
	      Note  that any changes to	the configuration after	this call have
	      indeterminate effects.  Returns FcFalse if this  operation  runs
	      out of memory.

       FcStrList *FcConfigGetConfigDirs	(FcConfig *config)
	      Returns the list of font directories specified in	the configura-
	      tion files for 'config'.	Does not include any subdirectories.

       FcStrList *FcConfigGetFontDirs (FcConfig	*config)
	      Returns the list of font directories in 'config'.	This  includes
	      the configured font directories along with any directories below
	      those in the filesystem.

       FcStrList *FcConfigGetConfigFiles (FcConfig *config)
	      Returns the list of known	configuration files used  to  generate
	      'config'.	  Note	that  this  will not include any configuration
	      done with	FcConfigParse.

       char *FcConfigGetCache (FcConfig	*config)
	      Returns the name of the file used	to store per-user font	infor-
	      mation.

       FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName	set)
	      Returns  one  of the two sets of fonts from the configuration as
	      specified	by 'set'.

       FcBlanks	*FcConfigGetBlanks (FcConfig *config)
	      Returns the FcBlanks object associated with the given configura-
	      tion, if no blanks were present in the configuration, this func-
	      tion will	return 0.

       int FcConfigGetRescanInverval (FcConfig *config)
	      Returns the interval between automatic checks of the  configura-
	      tion  (in	 seconds) specified in 'config'.  The configuration is
	      checked during a call  to	 FcFontList  when  this	 interval  has
	      passed since the last check.

       FcBool FcConfigSetRescanInverval	(FcConfig *config, int rescanInterval)
	      Sets the rescan interval;	returns	FcFalse	if an error occurred.

       FcBool FcConfigAppFontAddFile (FcConfig *config,	const char *file)
	      Adds an application-specific font	to the configuration.

       FcBool FcConfigAppFontAddDir (FcConfig *config, const char *dir)
	      Scans  the  specified directory for fonts, adding	each one found
	      to the application-specific set of fonts.

       void FcConfigAppFontClear (FcConfig *config)
	      Clears the set of	application-specific fonts.

       FcBool FcConfigSubstituteWithPat	(FcConfig *config, FcPattern  *p,  Fc-
       Pattern *p_pat FcMatchKind kind)
	      Performs	the  sequence  of  pattern modification	operations, if
	      'kind' is	FcMatchPattern,	then those tagged  as  pattern	opera-
	      tions  are  applied, else	if 'kind' is FcMatchFont, those	tagged
	      as font operations are applied and p_pat is used for <test> ele-
	      ments with target=pattern.

       FcBool  FcConfigSubstitute (FcConfig *config, FcPattern *p, FcMatchKind
       kind)
	      Calls FcConfigSubstituteWithPat setting p_pat to NULL.

       FcPattern *FcFontMatch (FcConfig	*config, FcPattern *p,	FcResult  *re-
       sult)
	      Returns  the  font  in  'config'	most close matching 'p'.  This
	      function should be  called  only	after  FcConfigSubstitute  and
	      FcDefaultSubstitute  have	been called for	'p'; otherwise the re-
	      sults will not be	correct.

       FcFontSet *FcFontSort (FcConfig *config,	FcPattern *p, FcBool trim, Fc-
       CharSet **csp, FcResult *result)	Returns	the list of fonts sorted by
	      closeness	 to  'p'.   If	'trim' is FcTrue, elements in the list
	      which don't include Unicode coverage not provided	by earlier el-
	      ements in	the list are elided.  The union	of Unicode coverage of
	      all of the fonts is returned in 'csp', if	 'csp'	is  not	 NULL.
	      This function should be called only after	FcConfigSubstitute and
	      FcDefaultSubstitute have been called for 'p'; otherwise the  re-
	      sults will not be	correct.

       The  returned  FcFontSet	 references  FcPattern structures which	may be
       shared by the return value from multiple	FcFontSort calls, applications
       must  not modify	these patterns.	 Instead, they should be passed, along
       with 'p'	to FcFontRenderPrepare which combines  them  into  a  complete
       pattern.

       The  FcFontSet returned by FcFontSort is	destroyed by caling FcFontSet-
       Destroy.

       FcPattern *FcFontRenderPrepare (FcConfig	*config, FcPattern  *pat,  Fc-
       Pattern *font)
	      Creates  a  new pattern consisting of elements of	'font' not ap-
	      pearing in 'pat',	elements of 'pat' not appearing	in 'font'  and
	      the  best	 matching  value  from 'pat' for elements appearing in
	      both.  The result	is passed to  FcConfigSubstitute  with	'kind'
	      FcMatchFont and then returned.

       FcFontSet *FcFontList (FcConfig *config,	FcPattern *p, FcObjectSet *os)
	      Selects  fonts  matching	'p', creates patterns from those fonts
	      containing only the objects in  'os'  and	 returns  the  set  of
	      unique such patterns.

       char *FcConfigFilename (const char *name)
	      Given  the specified external entity name, return	the associated
	      filename.	 This provides applications a way to  convert  various
	      configuration file references into filename form.

       A  null	or  empty 'name' indicates that	the default configuration file
       should be used; which file this references can be overridden  with  the
       FC_CONFIG_FILE  environment  variable.	Next,  if the name starts with
       '~', it refers to a file	in the current users home  directory.	Other-
       wise if the name	doesn't	start with '/',	it refers to a file in the de-
       fault configuration directory; the built-in default  directory  can  be
       overridden with the FC_CONFIG_DIR environment variable.

   Initialization
       These  functions	 provide some control over how the library is initial-
       ized.

       FcConfig	*FcInitLoadConfig (void)
	      Loads the	default	configuration file and returns	the  resulting
	      configuration.  Does not load any	font information.

       FcConfig	*FcInitLoadConfigAndFonts (void)
	      Loads  the  default  configuration  file	and builds information
	      about the	available fonts.  Returns the resulting	configuration.

       FcBool FcInit (void)
	      Loads the	default	configuration file and	the  fonts  referenced
	      therein  and sets	the default configuration to that result.  Re-
	      turns whether this process succeeded or  not.   If  the  default
	      configuration has	already	been loaded, this routine does nothing
	      and returns FcTrue.

       int FcGetVersion	(void)
	      Returns the version number of the	library.

       FcBool FcInitReinitialize (void)
	      Forces the default configuration file to be reloaded and	resets
	      the default configuration.

       FcBool FcInitBringUptoDate (void)
	      Checks  the rescan interval in the default configuration,	check-
	      ing the configuration if the interval has	passed	and  reloading
	      the configuration	if when	any changes are	detected.

   FcAtomic
       These functions provide a safe way to update config files, allowing on-
       going reading of	the old	config file while locked for writing  and  en-
       suring that a consistent	and complete version of	the config file	is al-
       ways available.

       FcAtomic	* FcAtomicCreate (const	FcChar8	  *file)
	      Creates a	data structure containing data needed to  control  ac-
	      cess  to 'file'.	Writing	is done	to a separate file.  Once that
	      file is complete,	the original configuration file	is  atomically
	      replaced	so  that  reading  process always see a	consistent and
	      complete file without the	need to	lock for reading.

       FcBool FcAtomicLock (FcAtomic *atomic)
	      Attempts to lock the file	referenced by 'atomic'.	  Returns  Fc-
	      False if the file	is locked by another process, else returns Fc-
	      True and leaves the file locked.

       FcChar8 *FcAtomicNewFile	(FcAtomic *atomic)
	      Returns the filename for writing a new version of	the file  ref-
	      erenced by 'atomic'.

       FcChar8 *FcAtomicOrigFile (FcAtomic *atomic)
	      Returns the file refernced by 'atomic'.

       FcBool FcAtomicReplaceOrig (FcAtomic *atomic)
	      Replaces	the  original file referenced by 'atomic' with the new
	      file.

       void FcAtomicDeleteNew (FcAtomic	*atomic)
	      Deletes the new file.

       void FcAtomicUnlock (FcAtomic *atomic)
	      Unlocks the file.

       void FcAtomicDestroy (FcAtomic *atomic)
	      Destroys 'atomic'.

   FreeType specific functions
       #include	<fontconfig/fcfreetype.h>
       While the fontconfig library doesn't insist that	FreeType  be  used  as
       the rasterization mechanism for fonts, it does provide some convenience
       functions.

       FT_UInt FcFreeTypeCharIndex (FT_Face face, FcChar32 ucs4)
	      Maps a Unicode char to a glyph index.  This function uses	infor-
	      mation  from several possible underlying encoding	tables to work
	      around broken fonts.  As a result, this function isn't  designed
	      to  be  used  in	performance sensitive areas; results from this
	      function are intended to be cached by higher level functions.

       FcCharSet *FcFreeTypeCharSet (FT_Face face, FcBlanks *blanks) Scans a
	      FreeType face and	returns	the  set  of  encoded  Unicode	chars.
	      This  scans  several encoding tables to build as complete	a list
	      as possible.  If 'blanks'	is not 0, the glyphs in	the  font  are
	      examined	and any	blank glyphs not in 'blanks' are not placed in
	      the returned FcCharSet.

       FcPattern *FcFreeTypeQuery (const char *file, int id, FcBlanks *blanks,
       int *count)
	      Constructs  a  pattern  representing  the	'id'th font in 'file'.
	      The number of fonts in 'file' is returned	in 'count'.

   XML specific	functions
       FcBool FcConfigParseAndLoad (FcConfig *config, const FcChar8 *file, Fc-
       Bool complain)
	      Walks  the  configuration	 in 'file' and constructs the internal
	      representation in	'config'.  Any include files  referenced  from
	      within  'file' will be loaded with FcConfigLoad and also parsed.
	      If 'complain' is FcFalse,	no warning will	be displayed if	'file'
	      does not exist.

   File	and Directory routines
       FcBool  FcFileScan (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache,
       FcBlanks	*blanks, const char *file, FcBool force)
	      Scans a single file and adds  all	 fonts	found  to  'set'.   If
	      'force'  is  FcTrue, then	the file is scanned even if associated
	      information is found in 'cache'.	If 'file' is a	directory,  it
	      is added to 'dirs'.

       FcBool  FcDirScan  (FcFontSet *set, FcStrSet *dirs, FcFileCache *cache,
       FcBlanks	*blanks, const char *dir, FcBool force)
	      Scans an entire directory	and adds all fonts found to 'set'.  If
	      'force'  is  FcTrue,  then the directory and all files within it
	      are scanned even if information is present in the	 per-directory
	      cache  file  or  'cache'.	 Any subdirectories found are added to
	      'dirs'.

       FcBool FcDirSave	(FcFontSet *set, FcStrSet *dirs, const char *dir)
	      Creates the per-directory	cache file for 'dir' and populates  it
	      with the fonts in	'set' and subdirectories in 'dirs'.

       FcBool FcDirCacheValid (const FcChar8 *cache_file)
	      Returns  FcTrue  if  'cache_file'	is no older than the directory
	      containing it, else FcFalse.

   FcStrSet and	FcStrList
       A data structure	for enumerating	 strings,  used	 to  list  directories
       while  scanning	the configuration as directories are added while scan-
       ning.

       FcStrSet	*FcStrSetCreate	(void)
	      Create an	empty set.

       FcBool FcStrSetMember (FcStrSet *set, const FcChar8 *s)
	      Returns whether 's' is a member of 'set'.

       FcBool FcStrSetAdd (FcStrSet *set, const	FcChar8	*s)
	      Adds a copy of 's' to 'set'.

       FcBool FcStrSetAddFilename (FcStrSet *set, const	FcChar8	*s)
	      Adds a copy 's' to 'set',	The copy is  created  with  FcStrCopy-
	      Filename	so that	leading	'~' values are replaced	with the value
	      of the HOME environment variable.

       FcBool FcStrSetDel (FcStrSet *set, const	FcChar8	*s)
	      Removes 's' from 'set', returning	FcTrue if  's'	was  a	member
	      else FcFalse.

       void FcStrSetDestroy (FcStrSet *set)
	      Destroys 'set'.

       FcStrList *FcStrListCreate (FcStrSet *set)
	      Creates an enumerator to list the	strings	in 'set'.

       FcChar8 *FcStrListNext (FcStrList *list)
	      Returns the next string in 'set'.

       void FcStrListDone (FcStrList *list)
	      Destroys the enumerator 'list'.

   String utilities
       int FcUtf8ToUcs4	(FcChar8 *src, FcChar32	*dst, int len)
	      Converts the next	Unicode	char from 'src'	into 'dst' and returns
	      the number of bytes containing the char.	'src' nust be at least
	      'len' bytes long.

       int FcUcs4ToUtf8	(FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN])
	      Converts	the Unicode char from 'src' into 'dst' and returns the
	      number of	bytes needed to	encode the char.

       FcBool FcUtf8Len	(FcChar8 *src, int len,	int *nchar, int	*wchar)
	      Counts the number	of Unicode chars  in  'len'  bytes  of	'src'.
	      Places  that  count  in 'nchar'.	'wchar'	contains 1, 2 or 4 de-
	      pending on the number of bytes needed to hold the	 largest  uni-
	      code  char counted.  The return value indicates whether 'src' is
	      a	well-formed UTF8 string.

       int FcUtf16ToUcs4 (FcChar8 *src,	FcEndian endian,  FcChar32  *dst,  int
       len)
	      Converts the next	Unicode	char from 'src'	into 'dst' and returns
	      the number of bytes containing the char. 'src' must be at	 least
	      'len' bytes long.	 Bytes of 'src'	are combined into 16-bit units
	      according	to 'endian'.

       FcBool FcUtf16Len (FcChar8 *src,	FcEndian endian, int len, int  *nchar,
       int *wchar)
	      Counts  the  number  of  Unicode	chars in 'len' bytes of	'src'.
	      Bytes of 'src' are combined into 16-bit units according to  'en-
	      dian'.   Places that count in 'nchar'.  'wchar' contains 1, 2 or
	      4	depending on the number	of bytes needed	to  hold  the  largest
	      unicode  char  counted.	The  return  value  indicates  whether
	      'string' is a well-formed	UTF16 string.

       FcChar8 *FcStrCopy (const FcChar8 *s)
	      Allocates	memory,	copies 's' and returns the  resulting  buffer.
	      Yes,  this is 'strdup', but that function	isn't available	on ev-
	      ery platform.

       FcChar8 *FcStrCopyFilename (const FcChar8 *s)
	      Just like	FcStrCopy except that  it  converts  any  leading  '~'
	      characters in 's'	to the value of	the HOME environment variable.

       int FcStrCmpIgnoreCase (const char *s1, const char *s2)
	      Returns  the  usual <0, 0, >0 result of comparing	's1' and 's2'.
	      This test	is case-insensitive in the ASCII range and will	 oper-
	      ate  properly  with  UTF8	 encoded strings, although it does not
	      check for	well formed strings.

       FcChar8 *FcStrDirname (const FcChar8 *file)
	      Returns the directory containing 'file'.

       FcChar8 *FcStrBasename (const FcChar8 *file)
	      Returns the filename of 'file' stripped of any leading directory
	      names.

CONFIGURATION FILE FORMAT
       Configuration  files for	fontconfig are stored in XML format; this for-
       mat makes external configuration	tools easier to	write and ensures that
       they  will  generate syntactically correct configuration	files.	As XML
       files are plain text, they can also be manipulated by the  expert  user
       using a text editor.

       The  fontconfig document	type definition	resides	in the external	entity
       "fonts.dtd"; this is normally stored in the default font	 configuration
       directory  (/etc/fonts).	  Each	configuration  file should contain the
       following structure:

	    <?xml version="1.0"?>
	    <!DOCTYPE fontconfig SYSTEM	"fonts.dtd">
	    <fontconfig>
	    ...
	    </fontconfig>

   <fontconfig>
       This is the top level element for a font	configuration and can  contain
       <dir>, <cache>, <include>, <match> and <alias> elements in any order.

   <dir>
       This  element  contains a directory name	which will be scanned for font
       files to	include	in the set of available	fonts.

   <cache>
       This element contains a file name for the per-user cache	of font	infor-
       mation.	 If  it	starts with '~', it refers to a	file in	the users home
       directory.  This	file is	used to	 hold  information  about  fonts  that
       isn't  present  in  the per-directory cache files.  It is automatically
       maintained by the fontconfig library.  The default  for	this  file  is
       ``~/.fonts.cache-<version>'', where <version> is	the font configuration
       file version number (currently 1).

   <include ignore_missing="no">
       This element contains the name of  an  additional  configuration	 file.
       When  the  XML  datatype	is traversed by	FcConfigParse, the contents of
       the file	will also be incorporated into the  configuration  by  passing
       the  filename  to  FcConfigLoadAndParse.	 If 'ignore_missing' is	set to
       "yes" instead of	the default "no", a missing file will elicit no	 warn-
       ing message from	the library.

   <config>
       This  element  provides a place to consolodate additional configuration
       information.  <config> can contain <blank> and <rescan> elements	in any
       order.

   <blank>
       Fonts  often  include  "broken" glyphs which appear in the encoding but
       are drawn as blanks on the screen.  Within the <blank>  element,	 place
       each  Unicode characters	which is supposed to be	blank in an <int> ele-
       ment.  Characters outside of this set which are drawn as	blank will  be
       elided from the set of characters supported by the font.	 <b

   <rescan>
       The <rescan> element holds an <int> element which indicates the default
       interval	between	 automatic  checks  for	 font  configuration  changes.
       Fontconfig will validate	all of the configuration files and directories
       and automatically rebuild the internal datastructures when this	inter-
       val passes.

   <match target="pattern">
       This element holds first	a (possibly empty) list	of <test> elements and
       then a (possibly	empty) list of <edit> elements.	 Patterns which	 match
       all of the tests	are subjected to all the edits.	 If 'target' is	set to
       "font" instead of the default "pattern",	then this element  applies  to
       the  font  name resulting from a	match rather than a font pattern to be
       matched.

   <test qual="any" name="property" compare="eq">
       This element contains a single value which is compared with the pattern
       property	 "property" (substitute	any of the property names seen above).
       'compare' can be	one of "eq", "not_eq", "less", "less_eq",  "more",  or
       "more_eq".   'qual' may either be the default, "any", in	which case the
       match succeeds if any value associated with the	property  matches  the
       test  value,  or	"all", in which	case all of the	values associated with
       the property must match the test	value.

   <edit name="property" mode="assign" binding="weak">
       This element contains a list of expression elements (any	of  the	 value
       or  operator  elements).	 The expression	elements are evaluated at run-
       time and	modify the property "property".	 The modification  depends  on
       whether	"property"  was	 matched  by one of the	associated <test> ele-
       ments, if so, the modification may affect the first matched value.  Any
       values  inserted	 into  the  property  are given	the indicated binding.
       'mode' is one of:
	      Mode	Operation with match			Operation without match
	      --------------------------------------------------
	      "assign"	Replace	matching value			Replace	all values
	      "assign_replace"		    Replace all	values	Replace	all values
	      "prepend"	Insert before matching value		Insert at head of list
	      "prepend_first"		    Insert at head of listInsert at head of list
	      "append"	Append after matching value		Append at end of list
	      "append_last"		    Append at end of listAppend	at end of list

   <int>
   <double>
   <string>
   <bool>
       These elements hold a single value of the indicated type.  <bool>  ele-
       ments hold either true or false.

   <matrix>
       This  element holds the four <double> elements of an affine transforma-
       tion.

   <name>
       Holds a property	name.  Evaluates to the	first value from the  property
       of the font, not	the pattern.

   <const>
       Holds  the  name	 of a constant;	these are always integers and serve as
       symbolic	names for common font values:

	      Constant	Property  CPP symbol
	      ------------------------------
	      light	weight	  FC_WEIGHT_LIGHT
	      medium	weight	  FC_WEIGHT_MEDIUM
	      demibold	weight	  FC_WEIGHT_DEMIBOLD
	      bold	weight	  FC_WEIGHT_BOLD
	      black	weight	  FC_WEIGHT_BLACK
	      roman	slant	  FC_SLANT_ROMAN
	      italic	slant	  FC_SLANT_ITALIC
	      oblique	slant	  FC_SLANT_OBLIQUE
	      proportional	  spacing   FC_PROPORTIONAL
	      mono	spacing	  FC_MONO
	      charcell	spacing	  FC_CHARCELL
	      unknown	rgba	  FC_RGBA_UNKNOWN
	      rgb	rgba	  FC_RGBA_RGB
	      bgr	rgba	  FC_RGBA_BGR
	      vrgb	rgba	  FC_RGBA_VRGB
	      vbgr	rgba	  FC_RGBA_VBGR
	      none	rgba	  FC_RGBA_NONE

   <or>
   <and>
   <plus>
   <minus>
   <times>
   <divide>
       These elements perform the specified operation on a list	of  expression
       elements.  <or> and <and> are boolean, not bitwise.

   <eq>
   <not_eq>
   <less>
   <less_eq>
   <more>
   <more_eq>
       These elements compare two values, producing a boolean result.

   <not>
       Inverts the boolean sense of its	one expression element

   <if>
       This element takes three	expression elements; if	the value of the first
       is true,	it produces the	value of the second, otherwise it produces the
       value of	the third.

   <alias>
       Alias elements provide a	shorthand notation for the set of common match
       operations needed to substitute one font	family for another.  They con-
       tain  a	<family>  element  followed by optional	<prefer>, <accept> and
       <default> elements.  Fonts matching the <family>	element	are edited  to
       prepend	the  list of <prefer>ed	families before	the matching <family>,
       append the <accept>able familys after the matching <family> and	append
       the <default> families to the end of the	family list.

   <family>
       Holds a single font family name

   <prefer>
   <accept>
   <default>
       These  hold  a list of <family> elements	to be used by the <alias> ele-
       ment.

EXAMPLE	CONFIGURATION FILE
   System configuration	file
       This is an example of a system-wide configuration file

       <?xml version="1.0"?>
       <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
       <!-- /etc/fonts/fonts.conf file to configure system font	access -->
       <fontconfig>
       <!--
	    Find fonts in these	directories
       -->
       <dir>/usr/X11R6/lib/X11/fonts/truetype</dir>
       <dir>/usr/X11R6/lib/X11/fonts/Type1</dir>

       <!--
	    Accept deprecated 'mono' alias, replacing it with 'monospace'
       -->
       <match target="pattern">
	    <test qual="any" name="family"><string>mono</string></test>
	    <edit name="family"	mode="assign"><string>monospace</string></edit>
       </match>

       <!--
	    Names not including	any well known alias are given 'sans'
       -->
       <match target="pattern">
	    <test qual="all" name="family" mode="not_eq">sans</test>
	    <test qual="all" name="family" mode="not_eq">serif</test>
	    <test qual="all" name="family" mode="not_eq">monospace</test>
	    <edit name="family"	mode="append_last"><string>sans</string></edit>
       </match>

       <!--
	    Load per-user customization	file, but don't	complain
	    if it doesn't exist
       -->
       <include	ignore_missing="yes">~/.fonts.conf</include>

       <!--
	    Alias well known font names	to available TrueType fonts.
	    These substitute TrueType faces for	similar	Type1
	    faces to improve screen appearance.
       -->
       <alias>
	    <family>Times</family>
	    <prefer><family>Times New Roman</family></prefer>
	    <default><family>serif</family></default>
       </alias>
       <alias>
	    <family>Helvetica</family>
	    <prefer><family>Verdana</family></prefer>
	    <default><family>sans</family></default>
       </alias>
       <alias>
	    <family>Courier</family>
	    <prefer><family>Courier New</family></prefer>
	    <default><family>monospace</family></default>
       </alias>

       <!--
	    Provide required aliases for standard names
	    Do these after the users configuration file	so that
	    any	aliases	there are used preferentially
       -->
       <alias>
	    <family>serif</family>
	    <prefer><family>Times New Roman</family></prefer>
       </alias>
       <alias>
	    <family>sans</family>
	    <prefer><family>Verdana</family></prefer>
       </alias>
       <alias>
	    <family>monospace</family>
	    <prefer><family>Andale Mono</family></prefer>
       </alias>
       </fontconfig>

   User	configuration file
       This is an example of a	per-user  configuration	 file  that  lives  in
       ~/.fonts.conf

       <?xml version="1.0"?>
       <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
       <!-- ~/.fonts.conf for per-user font configuration -->
       <fontconfig>

       <!--
	    Private font directory
       -->
       <dir>~/misc/fonts</dir>

       <!--
	    use	rgb sub-pixel ordering to improve glyph	appearance on
	    LCD	screens.  Changes affecting rendering, but not matching
	    should always use target="font".
       -->
       <match target="font">
	    <edit name="rgba" mode="assign"><const>rgb</const></edit>
       </match>
       </fontconfig>

FILES
       fonts.conf  contains  configuration  information	for the	fontconfig li-
       brary consisting	of directories to look at for font information as well
       as  instructions	 on editing program specified font patterns before at-
       tempting	to match the available fonts.  It is in	xml format.

       fonts.dtd is a DTD that	describes  the	format	of  the	 configuration
       files.

       local.conf is sourced by	the default system-wide	fonts.conf file.  Note
       that the	normal 'make install' procedure	for XFree86 is to replace  any
       existing	 fonts.conf  file  with	the new	version.  Place	any local cus-
       tomizations in local.conf which this file references.

       ~/.fonts.conf is	the conventional location for per-user font configura-
       tion,   although	 the  actual  location	is  specified  in  the	global
       fonts.conf file.

       ~/.fonts.cache-*	is the conventional  repository	 of  font  information
       that  isn't  found in the per-directory caches.	This file is automati-
       cally maintained	by fontconfig.

AUTHOR
       Keith Packard, member of	the XFree86 Project, Inc.

XFree86				  Version 1.0			 FONTCONFIG(3)

NAME | SYNOPSIS | DESCRIPTION | FUNCTIONAL OVERVIEW | LANG TAGS | DATATYPES | FUNCTIONS | CONFIGURATION FILE FORMAT | EXAMPLE CONFIGURATION FILE | FILES | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=fontconfig&sektion=3&manpath=XFree86+4.5.0>

home | help