This is fontconfig.info, produced by makeinfo version 4.8 from
fontconfig.texi.

INFO-DIR-SECTION Permissively licensed documentation
START-INFO-DIR-ENTRY
* fontconfig::                Managing font metainformation.
END-INFO-DIR-ENTRY


File: fontconfig.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)

Fontconfig
**********

This file documents fontconfig, a rendering-engine-independent library
for managing font metainformation (_i.e._, everything but the glyph
data themselves).  It is _not_ part of XEmacs.

  Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc.
Copyright © 2003 Stephen J. Turnbull, member of the XEmacs Project

  In the following notice, the term "Authors" refers to the copyright
holders listed above, and "Documentation" refers to this version of the
documentation supplied by Keith Packard, as adapted to Texinfo by
Stephen J. Turnbull.  The fontconfig library itself and the original
documentation are covered by a similar license.

  Permission to use, copy, modify, distribute, and sell this
Documentation for any purpose is hereby granted without fee, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in copies of the
Documentation, and that the names of the Authors not be used in
advertising or publicity pertaining to distribution of the
Documentation without specific, written prior permission.  The Authors
make no representations about the suitability of this Documentation for
any purpose.  It is provided "as is" without express or implied
warranty.

  THE AUTHORS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS DOCUMENTATION,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL THE AUTHORS BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS DOCUMENTATION.

* Menu:

* Copying::
* Overview::
* The fontconfig API::
* Configuration File Format::
* Files::
* Authors::

 --- The Detailed Node Listing ---

Overview

* Font Configuration::
* Font Properties::
* Font Matching::
* Font List Matching::
* Font Names::
* LANG Tags::

The fontconfig API

* Data Types::
* Functions::

Functions

* FcMatrix::
* FcCharSet::
* FcValue::
* FcPattern::
* FcFontSet::
* FcObjectSet::
* FcObjectType::
* Querying Fonts and Their Properties::
* Initialization::
* FcAtomic::
* FreeType-Specific Functions::
* XML-Specific Functions::
* File and Directory Routines::
* FcStrSet and FcStrList::
* String Utilities::

Configuration File Format

* Example System Configuration File::
* Example User Configuration File::


File: fontconfig.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top

1 Copying
*********

The fontconfig library and the accompanying documentation are covered by
the following copyright notice and license, except for this Texinfo
version which has additional authors but is otherwise substantially the
same.

  Copyright © 2002 Keith Packard, member of The XFree86 Project, Inc.

  Permission to use, copy, modify, distribute, and sell this software
and its documentation for any purpose is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Keith Packard not be
used in advertising or publicity pertaining to distribution of the
software without specific, written prior permission.  Keith Packard
makes no representations about the suitability of this software for any
purpose.  It is provided "as is" without express or implied warranty.

  KEITH PACKARD DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
EVENT SHALL KEITH PACKARD BE LIABLE FOR ANY SPECIAL, INDIRECT OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.


File: fontconfig.info,  Node: Overview,  Next: The fontconfig API,  Prev: Copying,  Up: Top

2 Overview
**********

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

  This manual describes fontconfig version 1.0.2.

  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.

* Menu:

* Font Configuration::
* Font Properties::
* Font Matching::
* Font List Matching::
* Font Names::
* LANG Tags::


File: fontconfig.info,  Node: Font Configuration,  Next: Font Properties,  Prev: Overview,  Up: Overview

2.1 Font Configuration
======================

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

  The intent is to make font configuration 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
applications to pick and choose appropriate functionality from the
library instead of forcing them to choose between this library and a
private configuration mechanism.  The hope is that this will ensure
that configuration of fonts for all applications can be centralized in
one place.  Centralizing font configuration will simplify and
regularize font installation and customization.


File: fontconfig.info,  Node: Font Properties,  Next: Font Matching,  Prev: Font Configuration,  Up: Overview

2.2 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.
Some symbolic constants are provided for common values or enumerated
types.  *Note Constants::, for the list of standard properties and
values.


File: fontconfig.info,  Node: Font Matching,  Next: Font List Matching,  Prev: Font Properties,  Up: Overview

2.3 Font Matching
=================

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

  Font matching starts with an application constructed pattern.  The
desired attributes of the resulting font are collected together in an
FcPattern object.  Each property of the pattern can contain one or more
values; these are listed in priority order; matches 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
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 associated sequence of editing operations to be
applied.

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

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

  There is one special case to this rule; family names are split into
two bindings; strong and weak.  Strong family names are given greater
precedence in the match than lang 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 rasterized.  Those must apply to the selected font, not the
original pattern as false matches will often occur.


File: fontconfig.info,  Node: Font List Matching,  Next: Font Names,  Prev: Font Matching,  Up: Overview

2.4 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 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 executing
the font substitutions.


File: fontconfig.info,  Node: Font Names,  Next: LANG Tags,  Prev: Font List Matching,  Up: Overview

2.5 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.  A hyphen or comma in a
family name must be escaped with a backslash.  The name needn't include
either families or point sizes; they can be elided.  If the family name
only is given, the hyphen may be omitted.  If there are no additional
properties, no trailing colon should be used.  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 1   The users preferred monospace font
                                 with artificial obliquing
     Mikachan\-PB-16             12 point Mikachan-PB


File: fontconfig.info,  Node: LANG Tags,  Prev: Font Names,  Up: Overview

2.6 LANG Tags
=============

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

  Fontconfig has orthographies for several languages built into the
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.


File: fontconfig.info,  Node: The fontconfig API,  Next: Configuration File Format,  Prev: Overview,  Up: Top

3 The fontconfig API
********************

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

* Menu:

* Constants::
* Data Types::
* Functions::


File: fontconfig.info,  Node: Constants,  Next: Data Types,  Prev: The fontconfig API,  Up: The fontconfig API

  While fontconfig is designed to be extensible, it provides a
comprehensive set of standard properties and values for fonts.

  The following table gives the list of standard font properties.  The
property name is represented as a string.  In C code a C preprocessor
symbol may be used to help with typo detection.

     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  Stretch glyphs horizontally, then hint
     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    Should glyphs be antialiased?
     hinting         FC_HINTING      Bool    Should the rasterizer use hinting?
     verticallayout  FC_VERTICAL_LAYOUT Bool Use vertical layout
     autohint        FC_AUTOHINT     Bool    Use autohinter instead of normal hinter
     globaladvance   FC_GLOBAL_ADVANCE Bool  Use 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   String  Which 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  Point->pixel conversion scale factor
     dpi             FC_DPI          Double  Target dots per inch
     rgba            FC_RGBA         Int     unknown, rgb, bgr, vrgb, vbgr, none
                                             - subpixel geometry
     source		FC_SOURCE	String  X11, freetype
     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
     fontversion	FC_FONTVERSION  Int     From 'head' table

  C code can check the fontconfig version number with the numerical
preprocessor constants `FC_MAJOR', `FC_MINOR', and `FC_REVISION', or
use the combined constant `FC_VERSION', defined as `FC_MAJOR*10000 +
FC_MINOR*100 + FC_REVISION'.

  The cache version is given by `FC_CACHE_VERSION', and is a string, not
an integer.  This is normally appended to the end of the cache file
name, so multiple versions of fontconfig can peacefully co-exist.  The
cache file names are defined as `FC_DIR_CACHE_FILE' and
`FC_USER_CACHE_FILE'.

  The Boolean constants are `FcFalse' (0) and `FcTrue' (1).

  Properties used to control the rasterizer, their preprocessor
constants, and their types, include:

     charwidth	FC_CHAR_WIDTH	Int
     charheight	FC_CHAR_HEIGHT	Int
     matrix          FC_MATRIX       FcMatrix

  Preprocessor constants are defined for common standard font weights.
All are Ints.

     FC_WEIGHT_LIGHT	    0
     FC_WEIGHT_MEDIUM    100
     FC_WEIGHT_DEMIBOLD  180
     FC_WEIGHT_BOLD	    200
     FC_WEIGHT_BLACK	    210

  Preprocessor constants are defined for common standard slants.  All
are Ints.

     FC_SLANT_ROMAN	    0
     FC_SLANT_ITALIC	    100
     FC_SLANT_OBLIQUE    110

  Preprocessor constants are defined for the three spacing types.  All
are Ints, but should be treated as symbolic constants.

     FC_PROPORTIONAL	    0
     FC_MONO		    100
     FC_CHARCELL	    110

  Preprocessor constants are defined for the subpixel orders.  All are
Ints, but should be treated as symbolic constants.

     FC_RGBA_UNKNOWN	    0
     FC_RGBA_RGB	    1
     FC_RGBA_BGR	    2
     FC_RGBA_VRGB	    3
     FC_RGBA_VBGR	    4
     FC_RGBA_NONE	    5


File: fontconfig.info,  Node: Data Types,  Next: Functions,  Prev: Constants,  Up: The fontconfig API

3.1 Data Types
==============

`FcChar8'
`FcChar16'
`FcChar32'
`FcBool'
     These are primitive data types; 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 operations are provided to
     manipulate these.

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

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

`FcType'
     Tags the kind of data stored in an FcValue.

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

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

          	type		Union member	Datatype

          	FcTypeVoid	(none)		(none)
          	FcTypeInteger	i		int
          	FcTypeDouble	d		double
          	FcTypeString	s		TcChar8 *
          	FcTypeBool	b		b
          	FcTypeMatrix	m		FcMatrix *
          	FcTypeCharSet	c		FcCharSet *
                  FcTypeFTFace    f               void *
                                  p               FcPattern *
                  FcTypeLangSet   l               FcLangSet *

`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;
          	} 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;
          	} FcObjectType;
     marks the type of a pattern element generated when parsing font
     names.  Applications can add new object types so that font names
     may contain the new elements.

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

`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* argument; passing 0 uses the default configuration.
     FcConfig objects hold two sets of fonts, the first contains those
     specified by the configuration, the second set holds those added
     by the application at run-time.  Interfaces that need to reference
     a particulat set use one of the FcSetName enumerated values.

`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 FcPattern objects.

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

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

`FcMatchKind'
     An enumeration containing `FcMatchPattern' and `FcMatchFont'.

`FcLangResult'
     An enumeration containing `FcLangEqual', `FcLangDifferentCountry',
     and `FcLangDifferentLang'.  Presumably `FcLangDifferentLang'
     implies `FcLangDifferentCountry'.

`FcSetName'
     An enumeration containing `FcSetSystem' and `FcSetApplication'.

`FcEndian'
     An enumeration containing `FcEndianBig' and `FcEndianLittle'.


File: fontconfig.info,  Node: Functions,  Prev: Data Types,  Up: The fontconfig API

3.2 Functions
=============

* Menu:

* FcMatrix::
* FcCharSet::
* FcValue::
* FcPattern::
* FcFontSet::
* FcObjectSet::
* FcObjectType::
* FcLangSet::
* Querying Fonts and Their Properties::
* Initialization::
* FcAtomic::
* FreeType-Specific Functions::
* XML-Specific Functions::
* File and Directory Routines::
* FcStrSet and FcStrList::
* String Utilities::


File: fontconfig.info,  Node: FcMatrix,  Next: FcCharSet,  Prev: Functions,  Up: Functions

3.2.1 FcMatrix
--------------

FcMatrix structures hold an affine transformation in matrix form.

     #define FcMatrixInit(m)	((m)->xx = (m)->yy = 1, (m)->xy = (m)->yx = 0)
  Initializes a matrix to the identify transformation.

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

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

 -- Function: void FcMatrixMultiply (FcMatrix *RESULT, const FcMatrix
          *A, const FcMatrix *varb)
     Multiplies 'a' and 'b' together, placing the result in 'result'.
     'result' may refer to the same matrix as either 'a' or 'b'.

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

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

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


File: fontconfig.info,  Node: FcCharSet,  Next: FcValue,  Prev: FcMatrix,  Up: Functions

3.2.2 FcCharSet
---------------

An FcCharSet is a boolean array indicating a set of unicode chars.
Those associated with a font are marked constant and cannot be edited.
FcCharSets may be reference counted internally to reduce memory
consumption; this may be visible to applications as the result of
FcCharSetCopy may return its argument, and that CharSet may remain
unmodifiable.

  When represented as a string, an FcCharSet is not a pure bitmap; octet
values are limited such that FcCharSet objects, when printed, are valid
ASCII characters.

 -- Function: FcCharSet * FcCharSetCreate (void)
     Creates an empty FcCharSet object.

 -- Function: void FcCharSetDestroy (FcCharSet *fcs)
     Frees an FcCharSet object.

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

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

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

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

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

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

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

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

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

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

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

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

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


File: fontconfig.info,  Node: FcValue,  Next: FcPattern,  Prev: FcCharSet,  Up: Functions

3.2.3 FcValue
-------------

FcValue is a structure containing a type tag and a union of all possible
data types.  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.

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

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

 -- Function: void FcValuePrint (const FcValue v)
     Prints an easily readable version of the value to stdout.  There is
     no provision for reparsing data in this format, it's just for
     diagnostics and debugging.


File: fontconfig.info,  Node: FcPattern,  Next: FcFontSet,  Prev: FcValue,  Up: Functions

3.2.4 FcPattern
---------------

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

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

 -- Function: void FcPatternDestroy (FcPattern *p)
     Destroys a pattern, in the process destroying all related values.

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

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

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

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

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

 -- Function: FcBool FcPatternAddInteger (FcPattern *p, const char
          *object, int i)
 -- Function: FcBool FcPatternAddDouble (FcPattern *p, const char
          *object, double d)
 -- Function: FcBool FcPatternAddString (FcPattern *p, const char
          *object, const char *s)
 -- Function: FcBool FcPatternAddMatrix (FcPattern *p, const char
          *object, const FcMatrix *s)
 -- Function: FcBool FcPatternAddCharSet (FcPattern *p, const char
          *object, const FcCharSet *c)
 -- Function: 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.

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

 -- Function: FcResult FcPatternGetInteger (FcPattern *p, const char
          *object, int id, int *i);
 -- Function: FcResult FcPatternGetDouble (FcPattern *p, const char
          *object, int id, double *d);
 -- Function: FcResult FcPatternGetString (FcPattern *p, const char
          *object, int id, char **const s);
 -- Function: FcResult FcPatternGetMatrix (FcPattern *p, const char
          *object, int id, FcMatrix **s);
 -- Function: FcResult FcPatternGetCharSet (FcPattern *p, const char
          *object, int id, FcCharSet **c);
 -- Function: FcResult FcPatternGetBool (FcPattern *p, const char
          *object, int id, 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.

 -- Function: FcPattern * FcPatternBuild (FcPattern *orig, ...);
 -- Function: FcPattern *FcPatternVaBuild (FcPattern *orig, va_list va)
     Builds a pattern using a list of objects, types and values.  Each
     value to be entered in the pattern is specified with three
     arguments:
       1. Object name, a string describing the property to be added.

       2. Object type, one of the FcType enumerated values

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

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

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

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

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

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

 -- Function: void FcDefaultSubstitute (FcPattern *pattern)
     Supplies default values for underspecified font patterns:
        * 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).

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

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


File: fontconfig.info,  Node: FcFontSet,  Next: FcObjectSet,  Prev: FcPattern,  Up: Functions

3.2.5 FcFontSet
---------------

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

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

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

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

 -- Function: void FcFontSetPrint (const FcFontSet *s)
     Prints an easily readable version of the font set to stdout.
     There is no provision for reparsing data in this format, it's just
     for diagnostics and debugging.


File: fontconfig.info,  Node: FcObjectSet,  Next: FcObjectType,  Prev: FcFontSet,  Up: Functions

3.2.6 FcObjectSet
-----------------

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

 -- Function: FcObjectSet *FcObjectSetCreate (void)
     Creates an empty set.

 -- Function: FcBool FcObjectSetAdd (FcObjectSet *os, const char
          *object)
     Adds a property name to the set.

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

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


File: fontconfig.info,  Node: FcObjectType,  Next: FcLangSet,  Prev: FcObjectSet,  Up: Functions

3.2.7 FcObjectType
------------------

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

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

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

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

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

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

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

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


File: fontconfig.info,  Node: FcLangSet,  Next: Querying Fonts and Their Properties,  Prev: FcObjectType,  Up: Functions

3.2.8 FcLangSet
---------------

An `FcLangSet' holds a set of RFC 3066 language tags, *Note LANG Tags::.
This module provides functions to determine whether a given language is
fully supported by a font.  Partial support can be determined using the
font's character set, *Note FcCharSet::.

 -- Function: FcLangSet *FcLangSetCreate (void);
     Create an empty `FcLangSet'.

 -- Function: void FcLangSetDestroy (FcLangSet *ls);
     Destroy a `FcLangSet', freeing any associated storage.

 -- Function: FcLangSet *FcLangSetCopy (const FcLangSet *ls);
     Copy LS to a newly allocated `FcLangSet'.

 -- Function: FcBool FcLangSetAdd (FcLangSet *ls, const FcChar8 *lang);
     Add LANG to `FcLangSet' LS.

 -- Function: FcLangResult FcLangSetHasLang (const FcLangSet *ls, const
          FcChar8 *lang);
     Check whether LANG is a member of `FcLangSet' LS.  Note that the
     return value is a `FcLangResult', not a Boolean.

 -- Function: FcLangResult FcLangSetCompare (const FcLangSet *lsa,
          const FcLangSet *lsb);
     #### Document me.

 -- Function: FcBool FcLangSetEqual (const FcLangSet *lsa, const
          FcLangSet *lsb);
     Check whether the `FcLangSet's LSA and LSB contain the same
     members.

 -- Function: FcChar32 FcLangSetHash (const FcLangSet *ls);
     Return a hash value; two `FcLangSet's which hash to different
     values cannot contain the same members.


File: fontconfig.info,  Node: Querying Fonts and Their Properties,  Next: Initialization,  Prev: FcLangSet,  Up: Functions

3.2.9 Querying Fonts and Their Properties
-----------------------------------------

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
significantly more accurate CharSet for applications.

 -- Function: FcBlanks *FcBlanksCreate (void)
     Creates an empty FcBlanks object.

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

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

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

  The site or user may specify substitutions for certain font patterns,
for convenience or to get more accurate results for the local
installation or preferences.  These functions execute the substitution
based on a specified configuration.

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

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

  The following functions return fonts that match a certain pattern.
`FcFontRenderPrepare' and `FcFontMatch' always return a single best
match.  `FcFontList' returns the list of fonts that match a a given
pattern on a certain set of properties.  `FcFontSort' returns the
entire list of fonts, sorted in order of match quality, possibly
filtering out fonts that do not provide additional characters beyond
those provided by preferred fonts.

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

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

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

     The FcFontSet returned by FcFontList is destroyed by calling
     FcFontSetDestroy.

 -- Function: FcFontSet *FcFontSort (FcConfig *config, FcPattern *p,
          FcBool trim, FcCharSet **csp, FcResult *result)
     Returns the list of all 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 pattern.

     The FcFontSet returned by FcFontSort is destroyed by calling
     FcFontSetDestroy.


File: fontconfig.info,  Node: Initialization,  Next: FcAtomic,  Prev: Querying Fonts and Their Properties,  Up: Functions

3.2.10 Initialization
---------------------

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

 -- Function: FcConfig *FcConfigCreate (void)
     Creates an empty configuration.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  These functions provide some control over how the default
configuration of the library is initialized.  (This configuration is
normally implicitly initialized.)

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

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

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

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

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

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

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


File: fontconfig.info,  Node: FcAtomic,  Next: FreeType-Specific Functions,  Prev: Initialization,  Up: Functions

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

 -- Function: 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 atomically replaced
     so that reading processes always see a consistent and complete
     file without the need to lock for reading.

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

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

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

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

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

 -- Function: void FcAtomicUnlock (FcAtomic *atomic)
     Unlocks the file.

 -- Function: void FcAtomicDestroy (FcAtomic *atomic)
     Destroys 'atomic'.


File: fontconfig.info,  Node: FreeType-Specific Functions,  Next: XML-Specific Functions,  Prev: FcAtomic,  Up: Functions

3.2.12 FreeType-Specific Functions
----------------------------------

     #include <fontconfig/fcfreetype.h>

  While the fontconfig library doesn't insist that FreeType be used as
the rasterization mechanism for fonts, it does provide some convenience
functions.

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

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

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


File: fontconfig.info,  Node: XML-Specific Functions,  Next: File and Directory Routines,  Prev: FreeType-Specific Functions,  Up: Functions

3.2.13 XML-Specific Functions
-----------------------------

 -- Function: 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: fontconfig.info,  Node: File and Directory Routines,  Next: FcStrSet and FcStrList,  Prev: XML-Specific Functions,  Up: Functions

3.2.14 File and Directory Routines
----------------------------------

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

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

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

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


File: fontconfig.info,  Node: FcStrSet and FcStrList,  Next: String Utilities,  Prev: File and Directory Routines,  Up: Functions

3.2.15 FcStrSet and FcStrList
-----------------------------

A data structure for enumerating strings, used to list directories while
scanning the configuration as directories are added while scanning.

 -- Function: FcStrSet *FcStrSetCreate (void)
     Create an empty set.

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

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

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

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

 -- Function: void FcStrSetDestroy (FcStrSet *set)
     Destroys 'set'.

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

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

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


File: fontconfig.info,  Node: String Utilities,  Prev: FcStrSet and FcStrList,  Up: Functions

3.2.16 String Utilities
-----------------------

 -- Function: 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' must be at least
     'len' bytes long.

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

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

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

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

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

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

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

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

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


File: fontconfig.info,  Node: Configuration File Format,  Next: Files,  Prev: The fontconfig API,  Up: Top

4 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>
     	...
     	</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.  The scan
     does not recurse into subdirectories.

`<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 configuration
     file.  When the XML datatype is traversed by FcConfigParse, the
     contents of the file will also be incorporated into the
     configuration by passing the filename to FcConfigLoadAndParse.  If
     'ignore_missing' is set to "yes" instead of the default "no", a
     missing file will elicit no warning message from the library.

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

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

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

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

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

`<edit name="property" mode="assign" binding="weak">'
     This element contains a list of expression elements (any of the
     value or operator elements).  The expression elements are
     evaluated at run-time and modify the property "property".  The
     modification depends on whether "property" was matched by one of
     the associated `<test>' 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 list		Insert at head of list
          "append"	Append after matching value	Append at end of list
          "append_last"	Append at end of list		Append at end of list

`<int>'
`<double>'
`<string>'
`<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 bitwise.

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

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

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

`<alias>'
     Alias elements provide a shorthand notation for the set of common
     match operations needed to substitute one font family for another.
     They 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 families 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 each hold a list of `<family>' elements to be used by the
     `<alias>' element.

* Menu:

* Example System Configuration File::
* Example User Configuration File::


File: fontconfig.info,  Node: Example System Configuration File,  Next: Example User Configuration File,  Prev: Configuration File Format,  Up: Configuration File Format

4.1 Example System Configuration File
=====================================

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

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

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

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

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

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

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


File: fontconfig.info,  Node: Example User Configuration File,  Prev: Example System Configuration File,  Up: Configuration File Format

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


File: fontconfig.info,  Node: Files,  Next: Authors,  Prev: Configuration File Format,  Up: Top

5 Files
*******

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

`fonts.conf'
     is the default system-wide font configuration file.  It 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,
     with DTD `fonts.dtd'.

`local.conf'
     is the conventional default location for local font configuration.
     It 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 customizations in local.conf which this file references.  It
     is in xml format, with DTD `fonts.dtd'.

`~/.fonts.conf'
     is the conventional location for per-user font configuration,
     although the actual location is specified in the global fonts.conf
     file.  It is in xml format, with DTD `fonts.dtd'.

`fonts.cache-*'
     is found in each font directory where fonts were found.  This file
     is automatically maintained by fontconfig.  It is a flat text
     table, and should be treated as opaque.

`~/.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.  It is a flat text table, and should be
     treated as opaque.


File: fontconfig.info,  Node: Authors,  Prev: Files,  Up: Top

6 Authors
*********

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

*Stephen J. Turnbull*
     member of the XEmacs Project



Tag Table:
Node: Top236
Node: Copying2801
Node: Overview4263
Node: Font Configuration4886
Node: Font Properties6496
Node: Font Matching7076
Node: Font List Matching10368
Node: Font Names11416
Node: LANG Tags12680
Node: The fontconfig API13507
Node: Constants13797
Node: Data Types18142
Node: Functions24431
Node: FcMatrix24882
Node: FcCharSet26220
Node: FcValue29408
Node: FcPattern30370
Node: FcFontSet36713
Node: FcObjectSet37588
Node: FcObjectType38403
Node: FcLangSet39828
Node: Querying Fonts and Their Properties41350
Node: Initialization45790
Node: FcAtomic51532
Node: FreeType-Specific Functions53162
Node: XML-Specific Functions54598
Node: File and Directory Routines55208
Node: FcStrSet and FcStrList56621
Node: String Utilities58037
Node: Configuration File Format60786
Node: Example System Configuration File68696
Node: Example User Configuration File71335
Node: Files72175
Node: Authors73824

End Tag Table
