MirBSD manpage: fontconfig(3)


FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

NAME

     fontconfig - Font configuration and customization library

SYNOPSIS

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

DESCRIPTION

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

FUNCTIONAL OVERVIEW

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

     FONT CONFIGURATION
     The configuration module consists of the FcConfig datatype,
     libexpat and FcConfigParse which walks over an XML tree and
     ammends a configuration with data found within.  From an
     external perspective, configuration of the library consists
     of generating a valid XML tree and feeding that to FcConfig-
     Parse.  The only other mechanism provided to applications
     for changing the running configuration is to add fonts and
     directories 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 pass-
     ing 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; applica-
     tions needing to do their own matching can access the avail-
     able 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 forc-
     ing them to choose between this library and a private confi-
     guration mechanism.  The hope is that this will ensure that
     configuration of fonts for all applications can be central-
     ized in one place.  Centralizing font configuration will
     make simplify and regularize font installation and customi-
     zation.

XFree86                    Version 1.0                          1

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

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

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

     FONT MATCHING
     Fontconfig performs matching by measuring the distance from
     a provided pattern to all of the available fonts in the sys-
     tem.  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 pat-
     tern.  The desired attributes of the resulting font are col-
     lected 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 con-
     sidered "closer" than matches later in the list.

XFree86                    Version 1.0                          2

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     The initial pattern is modified by applying the list of
     editing instructions specific to patterns found in the con-
     figuration; each consists 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 asso-
     ciated 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, char-
     set, 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
     elements while weak family names are given lower precedence
     than lang elements.  This permits the document language to
     drive font selection when any document specified font is
     unavailable.

     The pattern representing that font is augmented to include
     any 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, 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 raster-
     ized.  Those must apply to the selected font, not the origi-
     nal pattern as false matches will often occur.

XFree86                    Version 1.0                          3

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     FONT LIST MATCHING

     While many applications want to locate a single font best
     matching their search criteria, other applications need to
     build a set of fonts which can be used to present any
     Unicode data.  Fontconfig provides an API to generate a list
     sorted by the nearness of each font to the 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 unconditionally included in the
     list, or whether they are included only if they cover por-
     tions of Unicode not covered by any of the preceeding fonts.

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

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

LANG TAGS

     Each font in the database contains a list of languages it
     supports.  This is computed by comparing the Unicode cover-
     age 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

XFree86                    Version 1.0                          4

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     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.

DATATYPES

     FcChar8
     FcChar16
     FcChar32
     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
          symbols: FcFalse or FcTrue.

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

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

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

     FcType
          Tags the kind of data stored in an FcValue.

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

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

XFree86                    Version 1.0                          5

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

               } FcValue;

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

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

     FcFontSet

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

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

     FcObjectSet

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

XFree86                    Version 1.0                          6

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

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

     FcObjectType

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

     FcConstant

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

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

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

     FcConfig
          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* argu-
          ment; passing 0 uses the default configuration.  FcCon-
          fig 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

XFree86                    Version 1.0                          7

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

          one of the FcSetName enumerated values.

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

     FcResult
          Used as a return type for functions manipulating FcPat-
          tern objects.

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

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

FUNCTIONS

     FcMatrix
     FcMatrix structures hold an affine transformation in matrix
     form.

     Initializes a matrix to the identify transformation.

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

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

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

XFree86                    Version 1.0                          8

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     void FcMatrixRotate (FcMatrix *m, double c, double s)
          If 'c' is cos(angle) and 's' is sin(angle), FcMatrixRo-
          tate 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.

     FcCharSet
     An FcCharSet is a boolean array indicating a set of unicode
     chars.  Those associated with a font are marked constant and
     cannot be edited. FcCharSets may be reference counted inter-
     nally 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 increment the reference count on
          'src'.

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

     FcCharSet *FcCharSetIntersect (const FcCharSet *a, const FcChar-
      Set *b)
          Returns a set including only those chars found in both

XFree86                    Version 1.0                          9

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

          'a' and 'b'.

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

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

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

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

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

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

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

     FcChar32 FcCharSetFirstPage (const FcCharSet *a, FcChar32
      [FC_CHARSET_MAP_SIZE], FcChar32 *next)
          Builds an array of bits marking the first page of
          Unicode 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 *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.

XFree86                    Version 1.0                         10

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     FcValue
     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 harm-
          ing the new value.

     FcPattern
     An FcPattern is an opaque type that holds both patterns to
     match against the available fonts, as well as the informa-
     tion 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 *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)

XFree86                    Version 1.0                         11

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

          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 reference to
          any application-supplied data structure.

     FcBool FcPatternAddWeak (FcPattern *p, const char *object,
      FcValue value, FcBool append)
          FcPatternAddWeak is essentially the same as FcPatter-
          nAdd 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, dou-
      ble 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,

XFree86                    Version 1.0                         12

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

      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 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, FtType-
               String, "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.

XFree86                    Version 1.0                         13

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     void FcDefaultSubstitute (FcPattern *pattern)
          Supplies default values for underspecified font pat-
          terns:

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

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

          +    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 for-
          mat described above. The return value is not static,
          but instead refers to newly allocated memory which
          should be freed by the caller.

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

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

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

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

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

XFree86                    Version 1.0                         14

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     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.

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

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

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

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

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

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

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

XFree86                    Version 1.0                         15

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     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.

     FcBlanks
     An FcBlanks object holds a list of Unicode chars which are
     expected to be blank when drawn.  When scanning new fonts,
     any glyphs which are empty and not in this list will be
     assumed to be broken and not placed in the FcCharSet associ-
     ated with the font.  This provides 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, return-
          ing 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.

     FcConfig
     An FcConfig object holds the internal representation of a
     configuration. There is a default configuration which appli-
     cations 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

XFree86                    Version 1.0                         16

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

          it.  Note that calling this function with the return
          from FcConfigGetCurrent 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 confi-
          guration.  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 '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 information.

     FcFontSet *FcConfigGetFonts (FcConfig *config, FcSetName set)

XFree86                    Version 1.0                         17

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

          Returns one of the two sets of fonts from the confi-
          guration as specified by 'set'.

     FcBlanks *FcConfigGetBlanks (FcConfig *config)
          Returns the FcBlanks object associated with the given
          configuration, if no blanks were present in the confi-
          guration, 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 rescanIn-
      terval)
          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 opera-
          tions, if 'kind' is FcMatchPattern, 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.

XFree86                    Version 1.0                         18

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     FcPattern *FcFontMatch (FcConfig *config, FcPattern *p, FcResult
      *result)
          Returns the font in 'config' most close matching 'p'.
          This function should be called only after FcConfigSub-
          stitute 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 FcDefaultSub-
          stitute 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 FcFontRen-
     derPrepare 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', 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, FcOb-
      jectSet *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.

XFree86                    Version 1.0                         19

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     A null or empty 'name' indicates that the default configura-
     tion 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.  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_CONFIG_DIR environment variable.

     Initialization
     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 infor-
          mation.

     FcConfig *FcInitLoadConfigAndFonts (void)
          Loads the default configuration file and builds infor-
          mation about the available fonts.  Returns the result-
          ing 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 configura-
          tion, checking the configuration if the interval has
          passed and reloading the configuration if when any
          changes are detected.

XFree86                    Version 1.0                         20

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     FcAtomic
     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 con-
          trol access to 'file'. Writing is done to a separate
          file.  Once that file is complete, the original confi-
          guration 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 pro-
          cess, 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

XFree86                    Version 1.0                         21

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     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 per-
          formance 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 FcChar-
          Set.

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

XFree86                    Version 1.0                         22

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

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

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

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

     FcStrSet and FcStrList
     A data structure for enumerating strings, used to list
     directories while scanning the configuration as directories
     are added while 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 leading '~' values are
          replaced with the value of the HOME environment vari-
          able.

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

     void FcStrSetDestroy (FcStrSet *set)

XFree86                    Version 1.0                         23

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

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

XFree86                    Version 1.0                         24

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

          '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 environ-
          ment 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 FILE FORMAT

     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
     correct configuration files.  As XML files are plain text,
     they can also be manipulated by the expert user using a text
     editor.

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

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

XFree86                    Version 1.0                         25

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

          </fontconfig>

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

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

     <cache>
     This element contains a file name for the per-user cache of
     font 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 number (currently 1).

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

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

     <blank>
     Fonts often include "broken" glyphs which appear in the
     encoding but are drawn as blanks on the screen.  Within the
     <blank> element, place each Unicode characters which is 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

     <rescan>
     The <rescan> element holds an <int> element which indicates
     the default interval between automatic checks for font

XFree86                    Version 1.0                         26

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     configuration changes. Fontconfig will validate all of the
     configuration 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> ele-
     ments.  Patterns which match all of the tests are subjected
     to all the edits.  If 'target' is set to "font" instead of
     the default "pattern", then this element applies to the font
     name resulting from a match rather than a font pattern to be
     matched.

     <test qual="any" name="property" compare="eq">
     This element contains a single value which is compared with
     the pattern property "property" (substitute any of the pro-
     perty 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 "pro-
     perty".  The modification depends on whether "property" was
     matched by one of the associated <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

     <int>

     <double>

     <string>

XFree86                    Version 1.0                         27

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

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

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

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

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

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

     <or>

     <and>

     <plus>

     <minus>

     <times>

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

XFree86                    Version 1.0                         28

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     <eq>

     <not_eq>

     <less>

     <less_eq>

     <more>

     <more_eq>
     These elements compare two values, producing a boolean
     result.

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

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

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

     <family>
     Holds a single font family name

     <prefer>

     <accept>

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

EXAMPLE CONFIGURATION FILE

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

     <?xml version="1.0"?>
     <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
     <!-- /etc/fonts/fonts.conf file to configure system font access -->
     <fontconfig>
     <!--

XFree86                    Version 1.0                         29

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

          Find fonts in these directories
     -->
     <dir>/usr/X11R6/lib/X11/fonts/truetype</dir>
     <dir>/usr/X11R6/lib/X11/fonts/Type1</dir>

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

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

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

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

     <!--
          Provide required aliases for standard names

XFree86                    Version 1.0                         30

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

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

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

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

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

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

FILES

     fonts.conf contains configuration information for the
     fontconfig 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 confi-
     guration files.

     local.conf is sourced by the default system-wide fonts.conf

XFree86                    Version 1.0                         31

FONTCONFIG(3)       UNIX Programmer's Manual        FONTCONFIG(3)

     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 customizations in local.conf
     which this file references.

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

AUTHOR

     Keith Packard, member of the XFree86 Project, Inc.

XFree86                    Version 1.0                         32

Generated on 2021-12-07 11:07:08 by $MirOS: src/scripts/roff2htm,v 1.103 2021/01/23 20:24:35 tg Exp $ — This product includes material provided by mirabilos.

These manual pages and other documentation are copyrighted by their respective writers; their sources are available at the project’s CVSweb, AnonCVS and other mirrors. The rest is Copyright © 2002–2021 MirBSD.

This manual page’s HTML representation is supposed to be valid XHTML/1.1; if not, please send a bug report — diffs preferred.