4. FUNCTIONS

These are grouped by functionality, often using the main datatype being manipulated.

4.1. Initialization

Table of Contents
FcInitLoadConfig -- load configuration
FcInitLoadConfigAndFonts -- load configuration and font data
FcInit -- initialize fontconfig library
FcFini -- finalize fonconfig library
FcGetVersion -- library version number
FcInitReinitialize -- re-initialize library
FcInitBringUptoDate -- reload configuration files if needed

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

4.2. FcPattern

Table of Contents
FcPatternCreate -- Create a pattern
FcPatternDuplicate -- Copy a pattern
FcPatternReference -- Increment pattern reference count
FcPatternDestroy -- Destroy a pattern
FcPatternEqual -- Compare patterns
FcPatternEqualSubset -- Compare portions of patterns
FcPatternHash -- Compute a pattern hash value
FcPatternAdd -- Add a value to a pattern
FcPatternAddWeak -- Add a value to a pattern with weak binding
FcPatternAdd-Type -- Add a typed value to a pattern
FcPatternGet -- Return a value from a pattern
FcPatternGet-Type -- Return a typed value from a pattern
FcPatternBuild -- Create patterns from arguments
FcPatternDel -- Delete a property from a pattern
FcPatternRemove -- Remove one object of the specified type from the pattern
FcPatternPrint -- Print a pattern for debugging
FcDefaultSubstitute -- Perform default substitutions in a pattern
FcNameParse -- Parse a pattern string
FcNameUnparse -- Convert a pattern back into a string that can be parsed

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

4.3. FcFontSet

Table of Contents
FcFontSetCreate -- Create a font set
FcFontSetDestroy -- Destroy a font set
FcFontSetAdd -- Add to a font set
FcFontSetList -- List fonts from a set of font sets
FcFontSetMatch -- Return the best font from a set of font sets
FcFontSetPrint -- Print a set of patterns to stdout
FcFontSetSort -- Add to a font set
FcFontSetSortDestroy -- DEPRECATED destroy a font set

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

4.4. FcObjectSet

Table of Contents
FcObjectSetCreate -- Create an object set
FcObjectSetAdd -- Add to an object set
FcObjectSetDestroy -- Destroy an object set
FcObjectSetBuild -- Build object set from args

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.

4.5. FreeType specific functions

Table of Contents
FcFreeTypeCharIndex -- map Unicode to glyph id
FcFreeTypeCharSet -- compute unicode coverage
FcFreeTypeCharSetAndSpacing -- compute unicode coverage and spacing type
FcFreeTypeQuery -- compute pattern from font file (and index)
FcFreeTypeQueryFace -- compute pattern from FT_Face

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

4.6. FcValue

Table of Contents
FcValueDestroy -- Free a value
FcValueSave -- Copy a value
FcValuePrint -- Print a value to stdout
FcValueEqual -- Test two values for equality

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 typechecking, although that depends on careful programming.

4.7. FcCharSet

Table of Contents
FcCharSetCreate -- Create an empty character set
FcCharSetDestroy -- Destroy a character set
FcCharSetAddChar -- Add a character to a charset
FcCharSetCopy -- Copy a charset
FcCharSetEqual -- Compare two charsets
FcCharSetIntersect -- Intersect charsets
FcCharSetUnion -- Add charsets
FcCharSetSubtract -- Subtract charsets
FcCharSetHasChar -- Check a charset for a char
FcCharSetCount -- Count entries in a charset
FcCharSetIntersectCount -- Intersect and count charsets
FcCharSetSubtractCount -- Subtract and count charsets
FcCharSetIsSubset -- Test for charset inclusion
FcCharSetFirstPage -- Start enumerating charset contents
FcCharSetNextPage -- Continue enumerating charset contents
FcCharSetCoverage -- DEPRECATED return coverage for a Unicode page
FcCharSetNew -- DEPRECATED alias for FcCharSetCreate

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

4.8. FcLangSet

Table of Contents
FcLangSetCreate -- create a langset object
FcLangSetDestroy -- destroy a langset object
FcLangSetCopy -- copy a langset object
FcLangSetAdd -- add a language to a langset
FcLangSetCompare -- compare language sets
FcLangSetContains -- check langset subset relation
FcLangSetEqual -- test for matching langsets
FcLangSetHash -- return a hash value for a langset
FcLangSetHasLang -- test langset for language support
FcGetLangs -- Get list of languages
FcLangGetCharSet -- Get character map for a language

An FcLangSet is a set of language names (each of which include language and an optional territory). They are used when selecting fonts to indicate which languages the fonts need to support. Each font is marked, using language orthography information built into fontconfig, with the set of supported languages.

4.9. FcMatrix

Table of Contents
FcMatrixInit -- initialize an FcMatrix structure
FcMatrixCopy -- Copy a matrix
FcMatrixEqual -- Compare two matrices
FcMatrixMultiply -- Multiply matrices
FcMatrixRotate -- Rotate a matrix
FcMatrixScale -- Scale a matrix
FcMatrixShear -- Shear a matrix

FcMatrix structures hold an affine transformation in matrix form.

4.10. FcConfig

Table of Contents
FcConfigCreate -- Create a configuration
FcConfigDestroy -- Destroy a configuration
FcConfigSetCurrent -- Set configuration as default
FcConfigGetCurrent -- Return current configuration
FcConfigUptoDate -- Check timestamps on config files
FcConfigHome -- return the current home directory.
FcConfigEnableHome -- controls use of the home directory.
FcConfigBuildFonts -- Build font database
FcConfigGetConfigDirs -- Get config directories
FcConfigGetFontDirs -- Get font directories
FcConfigGetConfigFiles -- Get config files
FcConfigGetCache -- DEPRECATED used to return per-user cache filename
FcConfigGetCacheDirs -- return the list of directories searched for cache files
FcConfigGetFonts -- Get config font set
FcConfigGetBlanks -- Get config blanks
FcConfigGetRescanInterval -- Get config rescan interval
FcConfigSetRescanInterval -- Set config rescan interval
FcConfigAppFontAddFile -- Add font file to font database
FcConfigAppFontAddDir -- Add fonts from directory to font database
FcConfigAppFontClear -- Remove all app fonts from font database
FcConfigSubstituteWithPat -- Execute substitutions
FcConfigSubstitute -- Execute substitutions
FcFontMatch -- Return best font
FcFontSort -- Return list of matching fonts
FcFontRenderPrepare -- Prepare pattern for loading font file
FcFontList -- List fonts
FcConfigFilename -- Find a config file
FcConfigParseAndLoad -- load a configuration file

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.

4.11. FcObjectType

Table of Contents
FcNameRegisterObjectTypes -- Register object types
FcNameUnregisterObjectTypes -- Unregister object types
FcNameGetObjectType -- Lookup an object type

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

4.12. FcConstant

Table of Contents
FcNameRegisterConstants -- Register symbolic constants
FcNameUnregisterConstants -- Unregister symbolic constants
FcNameGetConstant -- Lookup symbolic constant
FcNameConstant -- Get the value for a symbolic constant

Provides for application-specified symbolic constants for font names.

4.13. FcBlanks

Table of Contents
FcBlanksCreate -- Create an FcBlanks
FcBlanksDestroy -- Destroy and FcBlanks
FcBlanksAdd -- Add a character to an FcBlanks
FcBlanksIsMember -- Query membership in an FcBlanks

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

4.14. FcAtomic

Table of Contents
FcAtomicCreate -- create an FcAtomic object
FcAtomicLock -- lock a file
FcAtomicNewFile -- return new temporary file name
FcAtomicOrigFile -- return original file name
FcAtomicReplaceOrig -- replace original with new
FcAtomicDeleteNew -- delete new file
FcAtomicUnlock -- unlock a file
FcAtomicDestroy -- destroy an FcAtomic object

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.

4.15. File and Directory routines

Table of Contents
FcFileScan -- scan a font file
FcFileIsDir -- check whether a file is a directory
FcDirScan -- DEPRECATED: formerly used to scan a font directory
FcDirSave -- DEPRECATED: formerly used to save a directory cache
FcDirCacheUnlink -- Remove all caches related to dir
FcDirCacheValid -- check directory cache
FcDirCacheLoad -- load a directory cache
FcDirCacheRead -- read or construct a directory cache
FcDirCacheLoadFile -- load a cache file
FcDirCacheUnload -- unload a cache file

These routines work with font files and directories, including font directory cache files.

4.16. FcCache routines

Table of Contents
FcCacheDir -- Return directory of cache
FcCacheCopySet -- Returns a copy of the fontset from cache
FcCacheSubdir -- Return the i'th subdirectory.
FcCacheNumSubdir -- Return the number of subdirectories in cache.
FcCacheNumFont -- Returns the number of fonts in cache.

These routines work with font directory caches, accessing their contents in limited ways. It is not expected that normal applications will need to use these functions.

4.17. FcStrSet and FcStrList

Table of Contents
FcStrSetCreate -- create a string set
FcStrSetMember -- check set for membership
FcStrSetEqual -- check sets for equality
FcStrSetAdd -- add to a string set
FcStrSetAddFilename -- add a filename to a string set
FcStrSetDel -- delete from a string set
FcStrSetDestroy -- destroy a string set
FcStrListCreate -- create a string iterator
FcStrListNext -- get next string in iteration
FcStrListDone -- destroy a string iterator

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

4.18. String utilities

Table of Contents
FcUtf8ToUcs4 -- convert UTF-8 to UCS4
FcUcs4ToUtf8 -- convert UCS4 to UTF-8
FcUtf8Len -- count UTF-8 encoded chars
FcUtf16ToUcs4 -- convert UTF-16 to UCS4
FcUtf16Len -- count UTF-16 encoded chars
FcIsLower -- check for lower case ASCII character
FcIsUpper -- check for upper case ASCII character
FcToLower -- convert upper case ASCII to lower case
FcStrCopy -- duplicate a string
FcStrDowncase -- create a lower case translation of a string
FcStrCopyFilename -- create a complete path from a filename
FcStrCmp -- compare UTF-8 strings
FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring case
FcStrStr -- locate UTF-8 substring
FcStrStrIgnoreCase -- locate UTF-8 substring ignoring ASCII case
FcStrPlus -- concatenate two strings
FcStrFree -- free a string
FcStrDirname -- directory part of filename
FcStrBasename -- last component of filename

Fontconfig manipulates many UTF-8 strings represented with the FcChar8 type. These functions are exposed to help applications deal with these UTF-8 strings in a locale-insensitive manner.