Unix/Linux Go Back    

RedHat 9 (Linux i386) - man page for fontconfig (redhat section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


       fontconfig - Font configuration and customization library

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

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

       Fontconfig contains two essential modules, the configuration module which builds an inter-
       nal  configuration  from XML files and the matching module which accepts font patterns and
       returns the nearest matching font.

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

       The  intent is to make font configurations relatively static, and shared by as many appli-
       cations 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
       retaining 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 library  and  perform  private	matching.
       The intent is to permit applications to pick and choose appropriate functionality from the
       library instead of forcing them to choose between this library and a private configuration
       mechanism.  The hope is that this will ensure that configuration of fonts for all applica-
       tions can be centralized in one place.  Centralizing font configuration will make simplify
       and regularize font installation and customization.

       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

       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 returned, but doesn't ensure	that  it  is  anything	like  the
       requested pattern.

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

       The initial pattern is modified by applying the list of editing instructions  specific  to
       patterns found in the configuration; each consists of a match predicate and a set of edit-
       ing 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 values 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, pixelsize, 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  ele-
       ments 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 unavail-

       The  pattern  representing  that  font is augmented to include any properties found in the
       pattern but not found in the font itself; this permits 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  pattern.
       This modified pattern is returned to the application.

       The return value contains sufficient information to locate and rasterize the font, includ-
       ing the file name, pixel size and other	rendering  data.   As  none  of  the  information
       involved  pertains to the FreeType library, 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.

       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	pattern.   Every  font	in  the system is considered, the best matching fonts are
       placed first.  The application then can select whether the remaining  fonts  are  uncondi-
       tionally 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  pat-
       terns  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  pat-
       tern and executing the font substitutions.

       Fontconfig provides a textual representation for patterns that the library 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  simulta-
       neously 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

       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.   Lan-
       guages 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 library.  No provision
       has been made for adding new ones aside from rebuilding the library.   It  currently  sup-
       ports  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.

       FcBool These are primitive datatypes; the FcChar* types hold precisely the number of  bits
	      stated  (if  supported  by the C implementation).  FcBool holds one of two CPP sym-
	      bols: FcFalse or FcTrue.

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

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

	      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.

	      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 *

	      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 specific fonts.  Each property can hold one or more values; con-
	      ventionally all of the same type, although the interface doesn't demand that.


		   typedef struct _FcFontSet {
			int nfont;
			int sfont;
			FcPattern **fonts;
		   } FcFontSet;
	      An FcFontSet contains a list of FcPatterns.  Internally fontconfig 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.

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


		   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 listing fonts.


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


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

	      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

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

	      holds a complete configuration of the library; there is one default  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.   Interfaces that need to reference a particulat set use
	      one of the FcSetName enumerated values.

	      Specifies one of the two sets of fonts available in  a  configuration;  FcSetSystem
	      for  those  fonts  specified  in the configuration and FcSetApplication which holds
	      fonts provided by the application.

	      Used as a return type for functions manipulating FcPattern objects.

		 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

	      Used for locking access to config files.	Provides a safe way to update  configura-
	      tion files.

       FcMatrix structures hold an affine transformation in matrix form.

       #define FcMatrixInit(m)	((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0)
	      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 FcMatrix *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 rotates  the  matrix  by

       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.

       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 consumption; this may be visible to applications as the result
       of FcCharSetCopy may return it's argument, and that CharSet may remain unmodifiable.

       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 anything more than incre-
	      ment 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
	      Builds an array of bits marking the first page of Unicode coverage 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
	      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 is a structure containing a type tag and a union of all possible  datatypes.   The
       tag  is an enum of type FcType and is intended to provide a measure of run-time typecheck-
       ing, although that depends on careful programming.

       void FcValueDestroy (FcValue v)
	      Frees any memory referenced by `v'.  Values of type FcTypeString, 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.

       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 values.

       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
	      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

       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  FcValue-
	      Save)  when  inserted  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 FcMatrix *s)
       FcBool FcPatternAddCharSet (FcPattern *p, const char *object, const FcCharSet *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 FcPatternAdd 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, FcValue *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, FcBool *b);
	      These are convenience functions that call FcPatternGet and verify 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 FcPatternGet 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	FcPatter-
	      nAdd<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

       FcBool FcPatternDel (FcPattern *p, const char *object)
	      Deletes all values associated with the property  `object',  returning  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 described above.  The
	      return value is not static, but instead refers  to  newly  allocated  memory  which
	      should be freed by the caller.

       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.

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

       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 property names.

       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'.

       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 nconsts)
	      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 registered, placing the
	      value of the constant in 'result' if present.

       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  pro-
       vides a significantly 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 indicated Unicode value.

       An FcConfig object holds the internal representation  of  a  configuration.   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 FcConfigGetCurrent will place the library in an inde-
	      terminate state.

       FcBool FcConfigSetCurrent (FcConfig *config)
	      Sets the current default configuration to  'config'.   Implicitly  calls	FcConfig-
	      BuildFonts 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 ver-
	      sion 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 configuration files for 'con-
	      fig'.  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 information.

       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 configuration, if no blanks
	      were present in the configuration, this function will return 0.

       int FcConfigGetRescanInverval (FcConfig *config)
	      Returns the interval between automatic checks of	the  configuration  (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,	FcPattern  *p_pat
       FcMatchKind kind)
	      Performs the sequence of pattern modification operations, if 'kind' is  FcMatchPat-
	      tern,  then  those  tagged  as  pattern  operations  are applied, else if 'kind' is
	      FcMatchFont, those tagged as font operations are applied	and  p_pat  is	used  for
	      <test> elements 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 *result)
	      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 results will not be correct.

       FcFontSet *FcFontSort (FcConfig *config, FcPattern *p, FcBool trim, FcCharSet **csp, FcRe-
       sult *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 elements 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 FcDefault-
	      Substitute have been called for 'p'; otherwise the results 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 FcFontSetDestroy.

       FcPattern *FcFontRenderPrepare (FcConfig *config, FcPattern *pat, FcPattern *font)
	      Creates a new pattern consisting of elements of 'font' not appearing in 'pat', ele-
	      ments 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 direc-
       tory.  Otherwise if the name doesn't start with '/', it refers to a file  in  the  default
       configuration directory; the built-in default directory can be overridden with the FC_CON-
       FIG_DIR environment variable.

       These functions provide some control over how the library is initialized.

       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.	Returns whether this process succeeded or
	      not.  If the default configuration has already been loaded, this routine does noth-
	      ing 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 config-

       FcBool FcInitBringUptoDate (void)
	      Checks the rescan interval in the default configuration, checking the configuration
	      if  the interval has passed and reloading the configuration if when any changes are

       These functions provide a safe way to update config files, allowing ongoing reading of the
       old  config file while locked for writing and ensuring that a consistent and complete ver-
       sion of the config file is always available.

       FcAtomic * FcAtomicCreate (const FcChar8   *file)
	      Creates a data structure containing data needed to control access to 'file'.  Writ-
	      ing  is done to a separate file.	Once that file is complete, the original configu-
	      ration 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 FcFalse if the file is
	      locked by another process, else returns FcTrue and leaves the file locked.

       FcChar8 *FcAtomicNewFile (FcAtomic *atomic)
	      Returns the filename for writing a new version of the file referenced 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 information 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, FcBool 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  dis-
	      played 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

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

       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 FcStrCopyFilename so that lead-
	      ing '~' 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 depending on the number of bytes needed to
	      hold the largest unicode 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 'endian'.  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 every 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 operate 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  files  for  fontconfig are stored in XML format; this format makes external
       configuration tools easier to write and ensures that they will generate syntactically cor-
       rect  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 config-
       uration file should contain the following structure:

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

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

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

       This element contains a file name for the per-user  cache  of  font  information.   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  num-
       ber (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 warning  message  from
       the library.

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

       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 sup-
       posed to be blank in an <int> element.  Characters outside of this set which are drawn  as
       blank will be elided from the set of characters supported by the font.  <b

       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 con-
       figuration  files  and  directories  and automatically rebuild the internal datastructures
       when this interval 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

   <test qual="any" name="property" compare="eq">
       This element contains a single value which is compared with the	pattern  property  "prop-
       erty"  (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 ele-
       ments).	The expression elements are evaluated at run-time and modify the property  "prop-
       erty".	The  modification depends on whether "property" was matched by one of the associ-
       ated <test> elements, 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

       These  elements	hold  a  single value of the indicated type.  <bool> elements hold either
       true or false.

       This element holds the four <double> elements of an affine transformation.

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

       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

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

       These elements compare two values, producing a boolean result.

       Inverts the boolean sense of its one expression element

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

       Alias elements provide a shorthand notation for the set of common match operations  needed
       to  substitute  one  font family for another.  They contain 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.

       Holds a single font family name

       These hold a list of <family> elements to be used by the <alias> element.

   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 -->
	    Find fonts in these directories

	    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>

	    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>

	    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.
	    <prefer><family>Times New Roman</family></prefer>
	    <prefer><family>Courier New</family></prefer>

	    Provide required aliases for standard names
	    Do these after the users configuration file so that
	    any aliases there are used preferentially
	    <prefer><family>Times New Roman</family></prefer>
	    <prefer><family>Andale Mono</family></prefer>

   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 -->

	    Private font directory

	    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>

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

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

       ~/.fonts.conf is the conventional location for per-user font configuration,  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 automatically maintained by fontconfig.

       Keith Packard, member of the XFree86 Project, Inc.

XFree86 				   Version 1.0				    FONTCONFIG(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 07:35 PM.