manpagez: man pages & more
man fontconfig(3)
Home | html | info | man
fontconfig(3)                                                    fontconfig(3)


       fontconfig - Font configuration and customization library


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


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


       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

       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
       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 applica-
       tions  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 con-
       figuration of fonts for all applications  can  be  centralized  in  one
       place.  Centralizing font configuration will make simplify and regular-
       ize 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

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

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

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


       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
       library.  No provision has been made for adding  new  ones  aside  from
       rebuilding 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.


       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.

              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

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


                   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.

              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.


                   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.


                   typedef  struct  _FcObjectType   {             const   char
              *object;           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.


                   typedef  struct _FcConstant {          const FcChar8 *name;
                        const  char  *object;            int   value;        }
              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 font.

              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.

              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.   Inter-
              faces  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 configura-
              tion; FcSetSystem for those fonts specified in the configuration
              and FcSetApplication which holds fonts provided by the  applica-

              Used  as  a  return  type  for  functions manipulating FcPattern

                 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

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


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

       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-

       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

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

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

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

       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
              Returns the number of chars that are in both 'a' and 'b'.

       FcChar32  FcCharSetSubtractCount  (const  FcCharSet *a, const FcCharSet
              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  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.

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

       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-

       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
              inserted into the pattern so that the library retains no  refer-
              ence 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

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

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

              o      Patterns  without  a  specified style or slant are set to

              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

       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 properties are to be  returned  in  the  patterns  from

       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.

       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
              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 ncon-
              Unregister 'nconsts' symbolic constants.

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

       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.

       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.

       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-

       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,
       FcPattern *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
              Calls FcConfigSubstituteWithPat setting p_pat to NULL.

       FcPattern  *FcFontMatch  (FcConfig  *config,  FcPattern  *p,   FcResult
              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, 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
              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
              FcDefaultSubstitute 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

       The  FcFontSet returned by FcFontSort is destroyed by caling FcFontSet-

       FcPattern  *FcFontRenderPrepare  (FcConfig  *config,  FcPattern   *pat,
       FcPattern *font)
              Creates a new pattern  consisting  of  elements  of  'font'  not
              appearing  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
       default  configuration directory; the built-in default directory can be
       overridden with the FC_CONFIG_DIR environment variable.

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

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

       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 version of the config file is
       always available.

       FcAtomic * FcAtomicCreate (const FcChar8   *file)
              Creates a data  structure  containing  data  needed  to  control
              access  to  'file'.   Writing  is done to a separate file.  Once
              that file is complete, the original configuration file is atomi-
              cally  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  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

       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

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

       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-

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


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

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

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

       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

       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

   <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

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

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

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

       Holds a single font family name

       These hold a list of <family> elements to be used by the  <alias>  ele-


   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

       <?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 format.

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

       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.


       Keith Packard, member of the XFree86 Project, Inc.

XFree86                           Version 1.0                    fontconfig(3)

Mac OS X 10.4 X11 - Generated Sat Apr 30 05:11:30 CDT 2005
© 2000-2024
Individual documents may contain additional copyright information.