doc/fontconfig-devel.txt

   1 Fontconfig Developers Reference, Version 2.13.0
   2
   3    Copyright © 2002 Keith Packard
   4
   5    Permission to use, copy, modify, distribute, and sell this
   6    software and its documentation for any purpose is hereby
   7    granted without fee, provided that the above copyright notice
   8    appear in all copies and that both that copyright notice and
   9    this permission notice appear in supporting documentation, and
  10    that the name of the author(s) not be used in advertising or
  11    publicity pertaining to distribution of the software without
  12    specific, written prior permission. The authors make no
  13    representations about the suitability of this software for any
  14    purpose. It is provided "as is" without express or implied
  15    warranty.
  16
  17    THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
  18    SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
  19    AND FITNESS, IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY
  20    SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  21    WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
  22    IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  23    ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  24    THIS SOFTWARE.
  25            _______________________________________________
  26
  27    Table of Contents
  28    DESCRIPTION
  29    FUNCTIONAL OVERVIEW
  30    Datatypes
  31    FUNCTIONS
  32
  33 DESCRIPTION
  34
  35    Fontconfig is a library designed to provide system-wide font
  36    configuration, customization and application access.
  37      __________________________________________________________
  38
  39 FUNCTIONAL OVERVIEW
  40
  41    Fontconfig contains two essential modules, the configuration
  42    module which builds an internal configuration from XML files
  43    and the matching module which accepts font patterns and returns
  44    the nearest matching font.
  45      __________________________________________________________
  46
  47 FONT CONFIGURATION
  48
  49    The configuration module consists of the FcConfig datatype,
  50    libexpat and FcConfigParse which walks over an XML tree and
  51    amends a configuration with data found within. From an external
  52    perspective, configuration of the library consists of
  53    generating a valid XML tree and feeding that to FcConfigParse.
  54    The only other mechanism provided to applications for changing
  55    the running configuration is to add fonts and directories to
  56    the list of application-provided font files.
  57
  58    The intent is to make font configurations relatively static,
  59    and shared by as many applications as possible. It is hoped
  60    that this will lead to more stable font selection when passing
  61    names from one application to another. XML was chosen as a
  62    configuration file format because it provides a format which is
  63    easy for external agents to edit while retaining the correct
  64    structure and syntax.
  65
  66    Font configuration is separate from font matching; applications
  67    needing to do their own matching can access the available fonts
  68    from the library and perform private matching. The intent is to
  69    permit applications to pick and choose appropriate
  70    functionality from the library instead of forcing them to
  71    choose between this library and a private configuration
  72    mechanism. The hope is that this will ensure that configuration
  73    of fonts for all applications can be centralized in one place.
  74    Centralizing font configuration will simplify and regularize
  75    font installation and customization.
  76      __________________________________________________________
  77
  78 FONT PROPERTIES
  79
  80    While font patterns may contain essentially any properties,
  81    there are some well known properties with associated types.
  82    Fontconfig uses some of these properties for font matching and
  83    font completion. Others are provided as a convenience for the
  84    application's rendering mechanism.
  85                  Property Definitions
  86
  87     Property       C Preprocessor Symbol  Type    Description
  88     ----------------------------------------------------
  89     family         FC_FAMILY              String  Font family names
  90     familylang     FC_FAMILYLANG          String  Language corresponding
  91  to
  92                                                   each family name
  93     style          FC_STYLE               String  Font style. Overrides
  94 weight
  95                                                   and slant
  96     stylelang      FC_STYLELANG           String  Language corresponding
  97  to
  98                                                   each style name
  99     fullname       FC_FULLNAME            String  Font face full name wh
 100 ere
 101                                                   different from family
 102 and
 103                                                   family + style
 104     fullnamelang   FC_FULLNAMELANG        String  Language corresponding
 105  to
 106                                                   each fullname
 107     slant          FC_SLANT               Int     Italic, oblique or rom
 108 an
 109     weight         FC_WEIGHT              Int     Light, medium, demibol
 110 d,
 111                                                   bold or black
 112     size           FC_SIZE                Double  Point size
 113     width          FC_WIDTH               Int     Condensed, normal or e
 114 xpanded
 115     aspect         FC_ASPECT              Double  Stretches glyphs horiz
 116 ontally
 117                                                   before hinting
 118     pixelsize      FC_PIXEL_SIZE          Double  Pixel size
 119     spacing        FC_SPACING             Int     Proportional, dual-wid
 120 th,
 121                                                   monospace or charcell
 122     foundry        FC_FOUNDRY             String  Font foundry name
 123     antialias      FC_ANTIALIAS           Bool    Whether glyphs can be
 124                                                   antialiased
 125     hinting        FC_HINTING             Bool    Whether the rasterizer
 126  should
 127                                                   use hinting
 128     hintstyle      FC_HINT_STYLE          Int     Automatic hinting styl
 129 e
 130     verticallayout FC_VERTICAL_LAYOUT     Bool    Use vertical layout
 131     autohint       FC_AUTOHINT            Bool    Use autohinter instead
 132  of
 133                                                   normal hinter
 134     globaladvance  FC_GLOBAL_ADVANCE      Bool    Use font global advanc
 135 e data (deprecated)
 136     file           FC_FILE                String  The filename holding t
 137 he font
 138     index          FC_INDEX               Int     The index of the font
 139 within
 140                                                   the file
 141     ftface         FC_FT_FACE             FT_Face Use the specified Free
 142 Type
 143                                                   face object
 144     rasterizer     FC_RASTERIZER          String  Which rasterizer is in
 145  use (deprecated)
 146     outline        FC_OUTLINE             Bool    Whether the glyphs are
 147  outlines
 148     scalable       FC_SCALABLE            Bool    Whether glyphs can be
 149 scaled
 150     scale          FC_SCALE               Double  Scale factor for point
 151 ->pixel
 152                                                   conversions (deprecate
 153 d)
 154     symbol         FC_SYMBOL              Bool    Whether font uses MS s
 155 ymbol-font encoding
 156     color          FC_COLOR               Bool    Whether any glyphs hav
 157 e color
 158     dpi            FC_DPI                 Double  Target dots per inch
 159     rgba           FC_RGBA                Int     unknown, rgb, bgr, vrg
 160 b,
 161                                                   vbgr, none - subpixel
 162 geometry
 163     lcdfilter      FC_LCD_FILTER          Int     Type of LCD filter
 164     minspace       FC_MINSPACE            Bool    Eliminate leading from
 165  line
 166                                                   spacing
 167     charset        FC_CHARSET             CharSet Unicode chars encoded
 168 by
 169                                                   the font
 170     lang           FC_LANG                LangSet Set of RFC-3066-style
 171                                                   languages this font su
 172 pports
 173     fontversion    FC_FONTVERSION         Int     Version number of the
 174 font
 175     capability     FC_CAPABILITY          String  List of layout capabil
 176 ities in
 177                                                   the font
 178     fontformat     FC_FONTFORMAT          String  String name of the fon
 179 t format
 180     embolden       FC_EMBOLDEN            Bool    Rasterizer should
 181                                                   synthetically embolden
 182  the font
 183     embeddedbitmap FC_EMBEDDED_BITMAP     Bool    Use the embedded bitma
 184 p instead
 185                                                   of the outline
 186     decorative     FC_DECORATIVE          Bool    Whether the style is a
 187  decorative
 188                                                   variant
 189     fontfeatures   FC_FONT_FEATURES       String  List of extra feature
 190 tags in
 191                                                   OpenType to be enabled
 192     namelang       FC_NAMELANG            String  Language name to be us
 193 ed for the
 194                                                   default value of famil
 195 ylang,
 196                                                   stylelang and fullname
 197 lang
 198     prgname        FC_PRGNAME             String  Name of the running pr
 199 ogram
 200     hash           FC_HASH                String  SHA256 hash value of t
 201 he font data
 202                                                   with "sha256:" prefix
 203 (deprecated)
 204     postscriptname FC_POSTSCRIPT_NAME     String  Font name in PostScrip
 205 t
 206      __________________________________________________________
 207
 208 Datatypes
 209
 210    Fontconfig uses abstract data types to hide internal
 211    implementation details for most data structures. A few
 212    structures are exposed where appropriate.
 213      __________________________________________________________
 214
 215 FcChar8, FcChar16, FcChar32, FcBool
 216
 217    These are primitive data types; the FcChar* types hold
 218    precisely the number of bits stated (if supported by the C
 219    implementation). FcBool holds one of two C preprocessor
 220    symbols: FcFalse or FcTrue.
 221      __________________________________________________________
 222
 223 FcMatrix
 224
 225    An FcMatrix holds an affine transformation, usually used to
 226    reshape glyphs. A small set of matrix operations are provided
 227    to manipulate these.
 228         typedef struct _FcMatrix {
 229                 double xx, xy, yx, yy;
 230         } FcMatrix;
 231      __________________________________________________________
 232
 233 FcCharSet
 234
 235    An FcCharSet is an abstract type that holds the set of encoded
 236    Unicode chars in a font. Operations to build and compare these
 237    sets are provided.
 238      __________________________________________________________
 239
 240 FcLangSet
 241
 242    An FcLangSet is an abstract type that holds the set of
 243    languages supported by a font. Operations to build and compare
 244    these sets are provided. These are computed for a font based on
 245    orthographic information built into the fontconfig library.
 246    Fontconfig has orthographies for all of the ISO 639-1 languages
 247    except for MS, NA, PA, PS, QU, RN, RW, SD, SG, SN, SU and ZA.
 248    If you have orthographic information for any of these
 249    languages, please submit them.
 250      __________________________________________________________
 251
 252 FcLangResult
 253
 254    An FcLangResult is an enumeration used to return the results of
 255    comparing two language strings or FcLangSet objects.
 256    FcLangEqual means the objects match language and territory.
 257    FcLangDifferentTerritory means the objects match in language
 258    but differ in territory. FcLangDifferentLang means the objects
 259    differ in language.
 260      __________________________________________________________
 261
 262 FcType
 263
 264    Tags the kind of data stored in an FcValue.
 265      __________________________________________________________
 266
 267 FcValue
 268
 269    An FcValue object holds a single value with one of a number of
 270    different types. The 'type' tag indicates which member is
 271    valid.
 272         typedef struct _FcValue {
 273                 FcType type;
 274                 union {
 275                         const FcChar8 *s;
 276                         int i;
 277                         FcBool b;
 278                         double d;
 279                         const FcMatrix *m;
 280                         const FcCharSet *c;
 281                         void *f;
 282                         const FcLangSet *l;
 283                 } u;
 284         } FcValue;
 285
 286                   FcValue Members
 287
 288         Type            Union member    Datatype
 289         --------------------------------
 290         FcTypeVoid      (none)          (none)
 291         FcTypeInteger   i               int
 292         FcTypeDouble    d               double
 293         FcTypeString    s               FcChar8 *
 294         FcTypeBool      b               b
 295         FcTypeMatrix    m               FcMatrix *
 296         FcTypeCharSet   c               FcCharSet *
 297         FcTypeFTFace    f               void * (FT_Face)
 298         FcTypeLangSet   l               FcLangSet *
 299      __________________________________________________________
 300
 301 FcPattern
 302
 303    holds a set of names with associated value lists; each name
 304    refers to a property of a font. FcPatterns are used as inputs
 305    to the matching code as well as holding information about
 306    specific fonts. Each property can hold one or more values;
 307    conventionally all of the same type, although the interface
 308    doesn't demand that.
 309      __________________________________________________________
 310
 311 FcFontSet
 312
 313         typedef struct _FcFontSet {
 314                 int nfont;
 315                 int sfont;
 316                 FcPattern **fonts;
 317         } FcFontSet;
 318
 319    An FcFontSet contains a list of FcPatterns. Internally
 320    fontconfig uses this data structure to hold sets of fonts.
 321    Externally, fontconfig returns the results of listing fonts in
 322    this format. 'nfont' holds the number of patterns in the
 323    'fonts' array; 'sfont' is used to indicate the size of that
 324    array.
 325      __________________________________________________________
 326
 327 FcStrSet, FcStrList
 328
 329    FcStrSet holds a list of strings that can be appended to and
 330    enumerated. Its unique characteristic is that the enumeration
 331    works even while strings are appended during enumeration.
 332    FcStrList is used during enumeration to safely and correctly
 333    walk the list of strings even while that list is edited in the
 334    middle of enumeration.
 335      __________________________________________________________
 336
 337 FcObjectSet
 338
 339         typedef struct _FcObjectSet {
 340                 int nobject;
 341                 int sobject;
 342                 const char **objects;
 343         } FcObjectSet;
 344
 345    holds a set of names and is used to specify which fields from
 346    fonts are placed in the the list of returned patterns when
 347    listing fonts.
 348      __________________________________________________________
 349
 350 FcObjectType
 351
 352         typedef struct _FcObjectType {
 353                 const char *object;
 354                 FcType type;
 355         } FcObjectType;
 356
 357    marks the type of a pattern element generated when parsing font
 358    names. Applications can add new object types so that font names
 359    may contain the new elements.
 360      __________________________________________________________
 361
 362 FcConstant
 363
 364         typedef struct _FcConstant {
 365             const FcChar8 *name;
 366             const char *object;
 367             int value;
 368         } FcConstant;
 369
 370    Provides for symbolic constants for new pattern elements. When
 371    'name' is seen in a font name, an 'object' element is created
 372    with value 'value'.
 373      __________________________________________________________
 374
 375 FcBlanks
 376
 377    holds a list of Unicode chars which are expected to be blank;
 378    unexpectedly blank chars are assumed to be invalid and are
 379    elided from the charset associated with the font.
 380
 381    FcBlanks is deprecated and should not be used in newly written
 382    code. It is still accepted by some functions for compatibility
 383    with older code but will be removed in the future.
 384      __________________________________________________________
 385
 386 FcFileCache
 387
 388    holds the per-user cache information for use while loading the
 389    font database. This is built automatically for the current
 390    configuration when that is loaded. Applications must always
 391    pass '0' when one is requested.
 392      __________________________________________________________
 393
 394 FcConfig
 395
 396    holds a complete configuration of the library; there is one
 397    default configuration, other can be constructed from XML data
 398    structures. All public entry points that need global data can
 399    take an optional FcConfig* argument; passing 0 uses the default
 400    configuration. FcConfig objects hold two sets of fonts, the
 401    first contains those specified by the configuration, the second
 402    set holds those added by the application at run-time.
 403    Interfaces that need to reference a particular set use one of
 404    the FcSetName enumerated values.
 405      __________________________________________________________
 406
 407 FcSetName
 408
 409    Specifies one of the two sets of fonts available in a
 410    configuration; FcSetSystem for those fonts specified in the
 411    configuration and FcSetApplication which holds fonts provided
 412    by the application.
 413      __________________________________________________________
 414
 415 FcResult
 416
 417    Used as a return type for functions manipulating FcPattern
 418    objects.
 419       FcResult Values
 420         Result Code             Meaning
 421         -----------------------------------------------------------
 422         FcResultMatch           Object exists with the specified ID
 423         FcResultNoMatch         Object doesn't exist at all
 424         FcResultTypeMismatch    Object exists, but the type doesn't matc
 425 h
 426         FcResultNoId            Object exists, but has fewer values
 427                                 than specified
 428         FcResultOutOfMemory     malloc failed
 429      __________________________________________________________
 430
 431 FcAtomic
 432
 433    Used for locking access to configuration files. Provides a safe
 434    way to update configuration files.
 435      __________________________________________________________
 436
 437 FcCache
 438
 439    Holds information about the fonts contained in a single
 440    directory. Normal applications need not worry about this as
 441    caches for font access are automatically managed by the
 442    library. Applications dealing with cache management may want to
 443    use some of these objects in their work, however the included
 444    'fc-cache' program generally suffices for all of that.
 445      __________________________________________________________
 446
 447 FUNCTIONS
 448
 449    These are grouped by functionality, often using the main data
 450    type being manipulated.
 451      __________________________________________________________
 452
 453 Initialization
 454
 455    Table of Contents
 456    FcInitLoadConfig -- load configuration
 457    FcInitLoadConfigAndFonts -- load configuration and font data
 458    FcInit -- initialize fontconfig library
 459    FcFini -- finalize fontconfig library
 460    FcGetVersion -- library version number
 461    FcInitReinitialize -- re-initialize library
 462    FcInitBringUptoDate -- reload configuration files if needed
 463
 464    These functions provide some control over how the library is
 465    initialized.
 466
 467 FcInitLoadConfig
 468
 469 Name
 470
 471    FcInitLoadConfig -- load configuration
 472
 473 Synopsis
 474
 475 #include <fontconfig/fontconfig.h>
 476
 477    FcConfig * FcInitLoadConfig(void);
 478
 479 Description
 480
 481    Loads the default configuration file and returns the resulting
 482    configuration. Does not load any font information.
 483
 484 FcInitLoadConfigAndFonts
 485
 486 Name
 487
 488    FcInitLoadConfigAndFonts -- load configuration and font data
 489
 490 Synopsis
 491
 492 #include <fontconfig/fontconfig.h>
 493
 494    FcConfig * FcInitLoadConfigAndFonts(void);
 495
 496 Description
 497
 498    Loads the default configuration file and builds information
 499    about the available fonts. Returns the resulting configuration.
 500
 501 FcInit
 502
 503 Name
 504
 505    FcInit -- initialize fontconfig library
 506
 507 Synopsis
 508
 509 #include <fontconfig/fontconfig.h>
 510
 511    FcBool FcInit(void);
 512
 513 Description
 514
 515    Loads the default configuration file and the fonts referenced
 516    therein and sets the default configuration to that result.
 517    Returns whether this process succeeded or not. If the default
 518    configuration has already been loaded, this routine does
 519    nothing and returns FcTrue.
 520
 521 FcFini
 522
 523 Name
 524
 525    FcFini -- finalize fontconfig library
 526
 527 Synopsis
 528
 529 #include <fontconfig/fontconfig.h>
 530
 531    void FcFini(void);
 532
 533 Description
 534
 535    Frees all data structures allocated by previous calls to
 536    fontconfig functions. Fontconfig returns to an uninitialized
 537    state, requiring a new call to one of the FcInit functions
 538    before any other fontconfig function may be called.
 539
 540 FcGetVersion
 541
 542 Name
 543
 544    FcGetVersion -- library version number
 545
 546 Synopsis
 547
 548 #include <fontconfig/fontconfig.h>
 549
 550    int FcGetVersion(void);
 551
 552 Description
 553
 554    Returns the version number of the library.
 555
 556 FcInitReinitialize
 557
 558 Name
 559
 560    FcInitReinitialize -- re-initialize library
 561
 562 Synopsis
 563
 564 #include <fontconfig/fontconfig.h>
 565
 566    FcBool FcInitReinitialize(void);
 567
 568 Description
 569
 570    Forces the default configuration file to be reloaded and resets
 571    the default configuration. Returns FcFalse if the configuration
 572    cannot be reloaded (due to configuration file errors,
 573    allocation failures or other issues) and leaves the existing
 574    configuration unchanged. Otherwise returns FcTrue.
 575
 576 FcInitBringUptoDate
 577
 578 Name
 579
 580    FcInitBringUptoDate -- reload configuration files if needed
 581
 582 Synopsis
 583
 584 #include <fontconfig/fontconfig.h>
 585
 586    FcBool FcInitBringUptoDate(void);
 587
 588 Description
 589
 590    Checks the rescan interval in the default configuration,
 591    checking the configuration if the interval has passed and
 592    reloading the configuration if when any changes are detected.
 593    Returns FcFalse if the configuration cannot be reloaded (see
 594    FcInitReinitialize). Otherwise returns FcTrue.
 595      __________________________________________________________
 596
 597 FcPattern
 598
 599    Table of Contents
 600    FcPatternCreate -- Create a pattern
 601    FcPatternDuplicate -- Copy a pattern
 602    FcPatternReference -- Increment pattern reference count
 603    FcPatternDestroy -- Destroy a pattern
 604    FcPatternEqual -- Compare patterns
 605    FcPatternEqualSubset -- Compare portions of patterns
 606    FcPatternFilter -- Filter the objects of pattern
 607    FcPatternHash -- Compute a pattern hash value
 608    FcPatternAdd -- Add a value to a pattern
 609    FcPatternAddWeak -- Add a value to a pattern with weak binding
 610    FcPatternAdd-Type -- Add a typed value to a pattern
 611    FcPatternGetWithBinding -- Return a value with binding from a
 612           pattern
 613
 614    FcPatternGet -- Return a value from a pattern
 615    FcPatternGet-Type -- Return a typed value from a pattern
 616    FcPatternBuild -- Create patterns from arguments
 617    FcPatternDel -- Delete a property from a pattern
 618    FcPatternRemove -- Remove one object of the specified type from
 619           the pattern
 620
 621    FcPatternPrint -- Print a pattern for debugging
 622    FcDefaultSubstitute -- Perform default substitutions in a
 623           pattern
 624
 625    FcNameParse -- Parse a pattern string
 626    FcNameUnparse -- Convert a pattern back into a string that can
 627           be parsed
 628
 629    FcPatternFormat -- Format a pattern into a string according to
 630           a format specifier
 631
 632    An FcPattern is an opaque type that holds both patterns to
 633    match against the available fonts, as well as the information
 634    about each font.
 635
 636 FcPatternCreate
 637
 638 Name
 639
 640    FcPatternCreate -- Create a pattern
 641
 642 Synopsis
 643
 644 #include <fontconfig/fontconfig.h>
 645
 646    FcPattern * FcPatternCreate(void);
 647
 648 Description
 649
 650    Creates a pattern with no properties; used to build patterns
 651    from scratch.
 652
 653 FcPatternDuplicate
 654
 655 Name
 656
 657    FcPatternDuplicate -- Copy a pattern
 658
 659 Synopsis
 660
 661 #include <fontconfig/fontconfig.h>
 662
 663    FcPattern * FcPatternDuplicate(const FcPattern *p);
 664
 665 Description
 666
 667    Copy a pattern, returning a new pattern that matches p. Each
 668    pattern may be modified without affecting the other.
 669
 670 FcPatternReference
 671
 672 Name
 673
 674    FcPatternReference -- Increment pattern reference count
 675
 676 Synopsis
 677
 678 #include <fontconfig/fontconfig.h>
 679
 680    void FcPatternReference(FcPattern *p);
 681
 682 Description
 683
 684    Add another reference to p. Patterns are freed only when the
 685    reference count reaches zero.
 686
 687 FcPatternDestroy
 688
 689 Name
 690
 691    FcPatternDestroy -- Destroy a pattern
 692
 693 Synopsis
 694
 695 #include <fontconfig/fontconfig.h>
 696
 697    void FcPatternDestroy(FcPattern *p);
 698
 699 Description
 700
 701    Decrement the pattern reference count. If all references are
 702    gone, destroys the pattern, in the process destroying all
 703    related values.
 704
 705 FcPatternEqual
 706
 707 Name
 708
 709    FcPatternEqual -- Compare patterns
 710
 711 Synopsis
 712
 713 #include <fontconfig/fontconfig.h>
 714
 715    FcBool FcPatternEqual(const FcPattern *pa, const FcPattern
 716    *pb);
 717
 718 Description
 719
 720    Returns whether pa and pb are exactly alike.
 721
 722 FcPatternEqualSubset
 723
 724 Name
 725
 726    FcPatternEqualSubset -- Compare portions of patterns
 727
 728 Synopsis
 729
 730 #include <fontconfig/fontconfig.h>
 731
 732    FcBool FcPatternEqualSubset(const FcPattern *pa, const
 733    FcPattern *pb, const FcObjectSet *os);
 734
 735 Description
 736
 737    Returns whether pa and pb have exactly the same values for all
 738    of the objects in os.
 739
 740 FcPatternFilter
 741
 742 Name
 743
 744    FcPatternFilter -- Filter the objects of pattern
 745
 746 Synopsis
 747
 748 #include <fontconfig/fontconfig.h>
 749
 750    FcPattern * FcPatternFilter(FcPattern *p, const FcObjectSet *);
 751
 752 Description
 753
 754    Returns a new pattern that only has those objects from p that
 755    are in os. If os is NULL, a duplicate of p is returned.
 756
 757 FcPatternHash
 758
 759 Name
 760
 761    FcPatternHash -- Compute a pattern hash value
 762
 763 Synopsis
 764
 765 #include <fontconfig/fontconfig.h>
 766
 767    FcChar32 FcPatternHash(const FcPattern *p);
 768
 769 Description
 770
 771    Returns a 32-bit number which is the same for any two patterns
 772    which are equal.
 773
 774 FcPatternAdd
 775
 776 Name
 777
 778    FcPatternAdd -- Add a value to a pattern
 779
 780 Synopsis
 781
 782 #include <fontconfig/fontconfig.h>
 783
 784    FcBool FcPatternAdd(FcPattern *p, const char *object, FcValue
 785    value, FcBool append);
 786
 787 Description
 788
 789    Adds a single value to the list of values associated with the
 790    property named `object. If `append is FcTrue, the value is
 791    added at the end of any existing list, otherwise it is inserted
 792    at the beginning. `value' is saved (with FcValueSave) when
 793    inserted into the pattern so that the library retains no
 794    reference to any application-supplied data structure.
 795
 796 FcPatternAddWeak
 797
 798 Name
 799
 800    FcPatternAddWeak -- Add a value to a pattern with weak binding
 801
 802 Synopsis
 803
 804 #include <fontconfig/fontconfig.h>
 805
 806    FcBool FcPatternAddWeak(FcPattern *p, const char *object,
 807    FcValue value, FcBool append);
 808
 809 Description
 810
 811    FcPatternAddWeak is essentially the same as FcPatternAdd except
 812    that any values added to the list have binding weak instead of
 813    strong.
 814
 815 FcPatternAdd-Type
 816
 817 Name
 818
 819    FcPatternAddInteger, FcPatternAddDouble, FcPatternAddString,
 820    FcPatternAddMatrix, FcPatternAddCharSet, FcPatternAddBool,
 821    FcPatternAddFTFace, FcPatternAddLangSet,
 822    FcPatternAddRange -- Add a typed value to a pattern
 823
 824 Synopsis
 825
 826 #include <fontconfig/fontconfig.h>
 827
 828    FcBool FcPatternAddInteger(FcPattern *p, const char *object,
 829    int i);
 830
 831    FcBool FcPatternAddDouble(FcPattern *p, const char *object,
 832    double d);
 833
 834    FcBool FcPatternAddString(FcPattern *p, const char *object,
 835    const FcChar8 *s);
 836
 837    FcBool FcPatternAddMatrix(FcPattern *p, const char *object,
 838    const FcMatrix *m);
 839
 840    FcBool FcPatternAddCharSet(FcPattern *p, const char *object,
 841    const FcCharSet *c);
 842
 843    FcBool FcPatternAddBool(FcPattern *p, const char *object,
 844    FcBool b);
 845
 846    FcBool FcPatternAddFTFace(FcPattern *p, const char *object,
 847    const FT_Facef);
 848
 849    FcBool FcPatternAddLangSet(FcPattern *p, const char *object,
 850    const FcLangSet *l);
 851
 852    FcBool FcPatternAddRange(FcPattern *p, const char *object,
 853    const FcRange *r);
 854
 855 Description
 856
 857    These are all convenience functions that insert objects of the
 858    specified type into the pattern. Use these in preference to
 859    FcPatternAdd as they will provide compile-time typechecking.
 860    These all append values to any existing list of values.
 861    FcPatternAddRange are available since 2.11.91.
 862
 863 FcPatternGetWithBinding
 864
 865 Name
 866
 867    FcPatternGetWithBinding -- Return a value with binding from a
 868    pattern
 869
 870 Synopsis
 871
 872 #include <fontconfig/fontconfig.h>
 873
 874    FcResult FcPatternGetWithBinding(FcPattern *p, const char
 875    *object, int id, FcValue *v, FcValueBinding *b);
 876
 877 Description
 878
 879    Returns in v the id'th value and b binding for that associated
 880    with the property object. The Value returned is not a copy, but
 881    rather refers to the data stored within the pattern directly.
 882    Applications must not free this value.
 883
 884 Since
 885
 886    version 2.12.5
 887
 888 FcPatternGet
 889
 890 Name
 891
 892    FcPatternGet -- Return a value from a pattern
 893
 894 Synopsis
 895
 896 #include <fontconfig/fontconfig.h>
 897
 898    FcResult FcPatternGet(FcPattern *p, const char *object, int id,
 899    FcValue *v);
 900
 901 Description
 902
 903    Returns in v the id'th value associated with the property
 904    object. The value returned is not a copy, but rather refers to
 905    the data stored within the pattern directly. Applications must
 906    not free this value.
 907
 908 FcPatternGet-Type
 909
 910 Name
 911
 912    FcPatternGetInteger, FcPatternGetDouble, FcPatternGetString,
 913    FcPatternGetMatrix, FcPatternGetCharSet, FcPatternGetBool,
 914    FcPatternGetFTFace, FcPatternGetLangSet,
 915    FcPatternGetRange -- Return a typed value from a pattern
 916
 917 Synopsis
 918
 919 #include <fontconfig/fontconfig.h>
 920
 921    FcResult FcPatternGetInteger(FcPattern *p, const char *object,
 922    int n, int *i);
 923
 924    FcResult FcPatternGetDouble(FcPattern *p, const char *object,
 925    int n, double *d);
 926
 927    FcResult FcPatternGetString(FcPattern *p, const char *object,
 928    int n, FcChar8 **s);
 929
 930    FcResult FcPatternGetMatrix(FcPattern *p, const char *object,
 931    int n, FcMatrix **s);
 932
 933    FcResult FcPatternGetCharSet(FcPattern *p, const char *object,
 934    int n, FcCharSet **c);
 935
 936    FcResult FcPatternGetBool(FcPattern *p, const char *object, int
 937    n, FcBool *b);
 938
 939    FcResult FcPatternGetFTFace(FcPattern *p, const char *object,
 940    int n, FT_Face *f);
 941
 942    FcResult FcPatternGetLangSet(FcPattern *p, const char *object,
 943    int n, FcLangSet **l);
 944
 945    FcResult FcPatternGetRange(FcPattern *p, const char *object,
 946    int n, FcRange **r);
 947
 948 Description
 949
 950    These are convenience functions that call FcPatternGet and
 951    verify that the returned data is of the expected type. They
 952    return FcResultTypeMismatch if this is not the case. Note that
 953    these (like FcPatternGet) do not make a copy of any data
 954    structure referenced by the return value. Use these in
 955    preference to FcPatternGet to provide compile-time
 956    typechecking. FcPatternGetRange are available since 2.11.91.
 957
 958 FcPatternBuild
 959
 960 Name
 961
 962    FcPatternBuild, FcPatternVaBuild, FcPatternVapBuild -- Create
 963    patterns from arguments
 964
 965 Synopsis
 966
 967 #include <fontconfig/fontconfig.h>
 968
 969    FcPattern * FcPatternBuild(FcPattern *pattern, ...);
 970
 971    FcPattern * FcPatternVaBuild(FcPattern *pattern, va_list va);
 972
 973    void FcPatternVapBuild(FcPattern *result, FcPattern *pattern,
 974    va_list va);
 975
 976 Description
 977
 978    Builds a pattern using a list of objects, types and values.
 979    Each value to be entered in the pattern is specified with three
 980    arguments:
 981
 982     1. Object name, a string describing the property to be added.
 983     2. Object type, one of the FcType enumerated values
 984     3. Value, not an FcValue, but the raw type as passed to any of
 985        the FcPatternAdd<type> functions. Must match the type of
 986        the second argument.
 987
 988    The argument list is terminated by a null object name, no
 989    object type nor value need be passed for this. The values are
 990    added to `pattern', if `pattern' is null, a new pattern is
 991    created. In either case, the pattern is returned. Example
 992 pattern = FcPatternBuild (0, FC_FAMILY, FcTypeString, "Times", (char *)
 993 0);
 994
 995    FcPatternVaBuild is used when the arguments are already in the
 996    form of a varargs value. FcPatternVapBuild is a macro version
 997    of FcPatternVaBuild which returns its result directly in the
 998    result variable.
 999
1000 FcPatternDel
1001
1002 Name
1003
1004    FcPatternDel -- Delete a property from a pattern
1005
1006 Synopsis
1007
1008 #include <fontconfig/fontconfig.h>
1009
1010    FcBool FcPatternDel(FcPattern *p, const char *object);
1011
1012 Description
1013
1014    Deletes all values associated with the property `object',
1015    returning whether the property existed or not.
1016
1017 FcPatternRemove
1018
1019 Name
1020
1021    FcPatternRemove -- Remove one object of the specified type from
1022    the pattern
1023
1024 Synopsis
1025
1026 #include <fontconfig/fontconfig.h>
1027
1028    FcBool FcPatternRemove(FcPattern *p, const char *object, int
1029    id);
1030
1031 Description
1032
1033    Removes the value associated with the property `object' at
1034    position `id', returning whether the property existed and had a
1035    value at that position or not.
1036
1037 FcPatternPrint
1038
1039 Name
1040
1041    FcPatternPrint -- Print a pattern for debugging
1042
1043 Synopsis
1044
1045 #include <fontconfig/fontconfig.h>
1046
1047    void FcPatternPrint(const FcPattern *p);
1048
1049 Description
1050
1051    Prints an easily readable version of the pattern to stdout.
1052    There is no provision for reparsing data in this format, it's
1053    just for diagnostics and debugging.
1054
1055 FcDefaultSubstitute
1056
1057 Name
1058
1059    FcDefaultSubstitute -- Perform default substitutions in a
1060    pattern
1061
1062 Synopsis
1063
1064 #include <fontconfig/fontconfig.h>
1065
1066    void FcDefaultSubstitute(FcPattern *pattern);
1067
1068 Description
1069
1070    Supplies default values for underspecified font patterns:
1071
1072      * Patterns without a specified style or weight are set to
1073        Medium
1074      * Patterns without a specified style or slant are set to
1075        Roman
1076      * Patterns without a specified pixel size are given one
1077        computed from any specified point size (default 12), dpi
1078        (default 75) and scale (default 1).
1079
1080 FcNameParse
1081
1082 Name
1083
1084    FcNameParse -- Parse a pattern string
1085
1086 Synopsis
1087
1088 #include <fontconfig/fontconfig.h>
1089
1090    FcPattern * FcNameParse(const FcChar8 *name);
1091
1092 Description
1093
1094    Converts name from the standard text format described above
1095    into a pattern.
1096
1097 FcNameUnparse
1098
1099 Name
1100
1101    FcNameUnparse -- Convert a pattern back into a string that can
1102    be parsed
1103
1104 Synopsis
1105
1106 #include <fontconfig/fontconfig.h>
1107
1108    FcChar8 * FcNameUnparse(FcPattern *pat);
1109
1110 Description
1111
1112    Converts the given pattern into the standard text format
1113    described above. The return value is not static, but instead
1114    refers to newly allocated memory which should be freed by the
1115    caller using free().
1116
1117 FcPatternFormat
1118
1119 Name
1120
1121    FcPatternFormat -- Format a pattern into a string according to
1122    a format specifier
1123
1124 Synopsis
1125
1126 #include <fontconfig/fontconfig.h>
1127
1128    FcChar8 * FcPatternFormat(FcPattern *pat, const FcChar8
1129    *format);
1130
1131 Description
1132
1133    Converts given pattern pat into text described by the format
1134    specifier format. The return value refers to newly allocated
1135    memory which should be freed by the caller using free(), or
1136    NULL if format is invalid.
1137
1138    The format is loosely modeled after printf-style format string.
1139    The format string is composed of zero or more directives:
1140    ordinary characters (not "%"), which are copied unchanged to
1141    the output stream; and tags which are interpreted to construct
1142    text from the pattern in a variety of ways (explained below).
1143    Special characters can be escaped using backslash. C-string
1144    style special characters like \n and \r are also supported
1145    (this is useful when the format string is not a C string
1146    literal). It is advisable to always escape curly braces that
1147    are meant to be copied to the output as ordinary characters.
1148
1149    Each tag is introduced by the character "%", followed by an
1150    optional minimum field width, followed by tag contents in curly
1151    braces ({}). If the minimum field width value is provided the
1152    tag will be expanded and the result padded to achieve the
1153    minimum width. If the minimum field width is positive, the
1154    padding will right-align the text. Negative field width will
1155    left-align. The rest of this section describes various
1156    supported tag contents and their expansion.
1157
1158    A simple tag is one where the content is an identifier. When
1159    simple tags are expanded, the named identifier will be looked
1160    up in pattern and the resulting list of values returned, joined
1161    together using comma. For example, to print the family name and
1162    style of the pattern, use the format "%{family} %{style}\n". To
1163    extend the family column to forty characters use
1164    "%-40{family}%{style}\n".
1165
1166    Simple tags expand to list of all values for an element. To
1167    only choose one of the values, one can index using the syntax
1168    "%{elt[idx]}". For example, to get the first family name only,
1169    use "%{family[0]}".
1170
1171    If a simple tag ends with "=" and the element is found in the
1172    pattern, the name of the element followed by "=" will be output
1173    before the list of values. For example, "%{weight=}" may expand
1174    to the string "weight=80". Or to the empty string if pattern
1175    does not have weight set.
1176
1177    If a simple tag starts with ":" and the element is found in the
1178    pattern, ":" will be printed first. For example, combining this
1179    with the =, the format "%{:weight=}" may expand to ":weight=80"
1180    or to the empty string if pattern does not have weight set.
1181
1182    If a simple tag contains the string ":-", the rest of the the
1183    tag contents will be used as a default string. The default
1184    string is output if the element is not found in the pattern.
1185    For example, the format "%{:weight=:-123}" may expand to
1186    ":weight=80" or to the string ":weight=123" if pattern does not
1187    have weight set.
1188
1189    A count tag is one that starts with the character "#" followed
1190    by an element name, and expands to the number of values for the
1191    element in the pattern. For example, "%{#family}" expands to
1192    the number of family names pattern has set, which may be zero.
1193
1194    A sub-expression tag is one that expands a sub-expression. The
1195    tag contents are the sub-expression to expand placed inside
1196    another set of curly braces. Sub-expression tags are useful for
1197    aligning an entire sub-expression, or to apply converters
1198    (explained later) to the entire sub-expression output. For
1199    example, the format "%40{{%{family} %{style}}}" expands the
1200    sub-expression to construct the family name followed by the
1201    style, then takes the entire string and pads it on the left to
1202    be at least forty characters.
1203
1204    A filter-out tag is one starting with the character "-"
1205    followed by a comma-separated list of element names, followed
1206    by a sub-expression enclosed in curly braces. The
1207    sub-expression will be expanded but with a pattern that has the
1208    listed elements removed from it. For example, the format
1209    "%{-size,pixelsize{sub-expr}}" will expand "sub-expr" with
1210    pattern sans the size and pixelsize elements.
1211
1212    A filter-in tag is one starting with the character "+" followed
1213    by a comma-separated list of element names, followed by a
1214    sub-expression enclosed in curly braces. The sub-expression
1215    will be expanded but with a pattern that only has the listed
1216    elements from the surrounding pattern. For example, the format
1217    "%{+family,familylang{sub-expr}}" will expand "sub-expr" with a
1218    sub-pattern consisting only the family and family lang elements
1219    of pattern.
1220
1221    A conditional tag is one starting with the character "?"
1222    followed by a comma-separated list of element conditions,
1223    followed by two sub-expression enclosed in curly braces. An
1224    element condition can be an element name, in which case it
1225    tests whether the element is defined in pattern, or the
1226    character "!" followed by an element name, in which case the
1227    test is negated. The conditional passes if all the element
1228    conditions pass. The tag expands the first sub-expression if
1229    the conditional passes, and expands the second sub-expression
1230    otherwise. For example, the format
1231    "%{?size,dpi,!pixelsize{pass}{fail}}" will expand to "pass" if
1232    pattern has size and dpi elements but no pixelsize element, and
1233    to "fail" otherwise.
1234
1235    An enumerate tag is one starting with the string "[]" followed
1236    by a comma-separated list of element names, followed by a
1237    sub-expression enclosed in curly braces. The list of values for
1238    the named elements are walked in parallel and the
1239    sub-expression expanded each time with a pattern just having a
1240    single value for those elements, starting from the first value
1241    and continuing as long as any of those elements has a value.
1242    For example, the format "%{[]family,familylang{%{family}
1243    (%{familylang})\n}}" will expand the pattern "%{family}
1244    (%{familylang})\n" with a pattern having only the first value
1245    of the family and familylang elements, then expands it with the
1246    second values, then the third, etc.
1247
1248    As a special case, if an enumerate tag has only one element,
1249    and that element has only one value in the pattern, and that
1250    value is of type FcLangSet, the individual languages in the
1251    language set are enumerated.
1252
1253    A builtin tag is one starting with the character "=" followed
1254    by a builtin name. The following builtins are defined:
1255
1256    unparse
1257           Expands to the result of calling FcNameUnparse() on the
1258           pattern.
1259
1260    fcmatch
1261           Expands to the output of the default output format of
1262           the fc-match command on the pattern, without the final
1263           newline.
1264
1265    fclist
1266           Expands to the output of the default output format of
1267           the fc-list command on the pattern, without the final
1268           newline.
1269
1270    fccat
1271           Expands to the output of the default output format of
1272           the fc-cat command on the pattern, without the final
1273           newline.
1274
1275    pkgkit
1276           Expands to the list of PackageKit font() tags for the
1277           pattern. Currently this includes tags for each family
1278           name, and each language from the pattern, enumerated and
1279           sanitized into a set of tags terminated by newline.
1280           Package management systems can use these tags to tag
1281           their packages accordingly.
1282
1283    For example, the format "%{+family,style{%{=unparse}}}\n" will
1284    expand to an unparsed name containing only the family and style
1285    element values from pattern.
1286
1287    The contents of any tag can be followed by a set of zero or
1288    more converters. A converter is specified by the character "|"
1289    followed by the converter name and arguments. The following
1290    converters are defined:
1291
1292    basename
1293           Replaces text with the results of calling
1294           FcStrBasename() on it.
1295
1296    dirname
1297           Replaces text with the results of calling FcStrDirname()
1298           on it.
1299
1300    downcase
1301           Replaces text with the results of calling
1302           FcStrDowncase() on it.
1303
1304    shescape
1305           Escapes text for one level of shell expansion. (Escapes
1306           single-quotes, also encloses text in single-quotes.)
1307
1308    cescape
1309           Escapes text such that it can be used as part of a C
1310           string literal. (Escapes backslash and double-quotes.)
1311
1312    xmlescape
1313           Escapes text such that it can be used in XML and HTML.
1314           (Escapes less-than, greater-than, and ampersand.)
1315
1316    delete(chars)
1317           Deletes all occurrences of each of the characters in
1318           chars from the text. FIXME: This converter is not UTF-8
1319           aware yet.
1320
1321    escape(chars)
1322           Escapes all occurrences of each of the characters in
1323           chars by prepending it by the first character in chars.
1324           FIXME: This converter is not UTF-8 aware yet.
1325
1326    translate(from,to)
1327           Translates all occurrences of each of the characters in
1328           from by replacing them with their corresponding
1329           character in to. If to has fewer characters than from,
1330           it will be extended by repeating its last character.
1331           FIXME: This converter is not UTF-8 aware yet.
1332
1333    For example, the format "%{family|downcase|delete( )}\n" will
1334    expand to the values of the family element in pattern,
1335    lower-cased and with spaces removed.
1336
1337 Since
1338
1339    version 2.9.0
1340      __________________________________________________________
1341
1342 FcFontSet
1343
1344    Table of Contents
1345    FcFontSetCreate -- Create a font set
1346    FcFontSetDestroy -- Destroy a font set
1347    FcFontSetAdd -- Add to a font set
1348    FcFontSetList -- List fonts from a set of font sets
1349    FcFontSetMatch -- Return the best font from a set of font sets
1350    FcFontSetPrint -- Print a set of patterns to stdout
1351    FcFontSetSort -- Add to a font set
1352    FcFontSetSortDestroy -- DEPRECATED destroy a font set
1353
1354    An FcFontSet simply holds a list of patterns; these are used to
1355    return the results of listing available fonts.
1356
1357 FcFontSetCreate
1358
1359 Name
1360
1361    FcFontSetCreate -- Create a font set
1362
1363 Synopsis
1364
1365 #include <fontconfig/fontconfig.h>
1366
1367    FcFontSet * FcFontSetCreate(void);
1368
1369 Description
1370
1371    Creates an empty font set.
1372
1373 FcFontSetDestroy
1374
1375 Name
1376
1377    FcFontSetDestroy -- Destroy a font set
1378
1379 Synopsis
1380
1381 #include <fontconfig/fontconfig.h>
1382
1383    void FcFontSetDestroy(FcFontSet *s);
1384
1385 Description
1386
1387    Destroys a font set. Note that this destroys any referenced
1388    patterns as well.
1389
1390 FcFontSetAdd
1391
1392 Name
1393
1394    FcFontSetAdd -- Add to a font set
1395
1396 Synopsis
1397
1398 #include <fontconfig/fontconfig.h>
1399
1400    FcBool FcFontSetAdd(FcFontSet *s, FcPattern *font);
1401
1402 Description
1403
1404    Adds a pattern to a font set. Note that the pattern is not
1405    copied before being inserted into the set. Returns FcFalse if
1406    the pattern cannot be inserted into the set (due to allocation
1407    failure). Otherwise returns FcTrue.
1408
1409 FcFontSetList
1410
1411 Name
1412
1413    FcFontSetList -- List fonts from a set of font sets
1414
1415 Synopsis
1416
1417 #include <fontconfig/fontconfig.h>
1418
1419    FcFontSet * FcFontSetList(FcConfig *config, FcFontSet **sets,
1420    intnsets, FcPattern *pattern, FcObjectSet *object_set);
1421
1422 Description
1423
1424    Selects fonts matching pattern from sets, creates patterns from
1425    those fonts containing only the objects in object_set and
1426    returns the set of unique such patterns. If config is NULL, the
1427    default configuration is checked to be up to date, and used.
1428
1429 FcFontSetMatch
1430
1431 Name
1432
1433    FcFontSetMatch -- Return the best font from a set of font sets
1434
1435 Synopsis
1436
1437 #include <fontconfig/fontconfig.h>
1438
1439    FcPattern * FcFontSetMatch(FcConfig *config, FcFontSet **sets,
1440    intnsets, FcPattern *pattern, FcResult *result);
1441
1442 Description
1443
1444    Finds the font in sets most closely matching pattern and
1445    returns the result of FcFontRenderPrepare for that font and the
1446    provided pattern. This function should be called only after
1447    FcConfigSubstitute and FcDefaultSubstitute have been called for
1448    pattern; otherwise the results will not be correct. If config
1449    is NULL, the current configuration is used. Returns NULL if an
1450    error occurs during this process.
1451
1452 FcFontSetPrint
1453
1454 Name
1455
1456    FcFontSetPrint -- Print a set of patterns to stdout
1457
1458 Synopsis
1459
1460 #include <fontconfig/fontconfig.h>
1461
1462    void FcFontSetPrint(FcFontSet *set);
1463
1464 Description
1465
1466    This function is useful for diagnosing font related issues,
1467    printing the complete contents of every pattern in set. The
1468    format of the output is designed to be of help to users and
1469    developers, and may change at any time.
1470
1471 FcFontSetSort
1472
1473 Name
1474
1475    FcFontSetSort -- Add to a font set
1476
1477 Synopsis
1478
1479 #include <fontconfig/fontconfig.h>
1480
1481    FcFontSetSort(FcConfig *config, FcFontSet **sets, intnsets,
1482    FcPattern *pattern, FcBool trim, FcCharSet **csp, FcResult
1483    *result);
1484
1485 Description
1486
1487    Returns the list of fonts from sets sorted by closeness to
1488    pattern. If trim is FcTrue, elements in the list which don't
1489    include Unicode coverage not provided by earlier elements in
1490    the list are elided. The union of Unicode coverage of all of
1491    the fonts is returned in csp, if csp is not NULL. This function
1492    should be called only after FcConfigSubstitute and
1493    FcDefaultSubstitute have been called for p; otherwise the
1494    results will not be correct.
1495
1496    The returned FcFontSet references FcPattern structures which
1497    may be shared by the return value from multiple FcFontSort
1498    calls, applications cannot modify these patterns. Instead, they
1499    should be passed, along with pattern to FcFontRenderPrepare
1500    which combines them into a complete pattern.
1501
1502    The FcFontSet returned by FcFontSetSort is destroyed by calling
1503    FcFontSetDestroy.
1504
1505 FcFontSetSortDestroy
1506
1507 Name
1508
1509    FcFontSetSortDestroy -- DEPRECATED destroy a font set
1510
1511 Synopsis
1512
1513 #include <fontconfig/fontconfig.h>
1514
1515    FcFontSetSortDestroy(FcFontSet *set);
1516
1517 Description
1518
1519    This function is DEPRECATED. FcFontSetSortDestroy destroys set
1520    by calling FcFontSetDestroy. Applications should use
1521    FcFontSetDestroy directly instead.
1522      __________________________________________________________
1523
1524 FcObjectSet
1525
1526    Table of Contents
1527    FcObjectSetCreate -- Create an object set
1528    FcObjectSetAdd -- Add to an object set
1529    FcObjectSetDestroy -- Destroy an object set
1530    FcObjectSetBuild -- Build object set from args
1531
1532    An FcObjectSet holds a list of pattern property names; it is
1533    used to indicate which properties are to be returned in the
1534    patterns from FcFontList.
1535
1536 FcObjectSetCreate
1537
1538 Name
1539
1540    FcObjectSetCreate -- Create an object set
1541
1542 Synopsis
1543
1544 #include <fontconfig/fontconfig.h>
1545
1546    FcObjectSet * FcObjectSetCreate(void);
1547
1548 Description
1549
1550    Creates an empty set.
1551
1552 FcObjectSetAdd
1553
1554 Name
1555
1556    FcObjectSetAdd -- Add to an object set
1557
1558 Synopsis
1559
1560 #include <fontconfig/fontconfig.h>
1561
1562    FcBool FcObjectSetAdd(FcObjectSet *os, const char *object);
1563
1564 Description
1565
1566    Adds a property name to the set. Returns FcFalse if the
1567    property name cannot be inserted into the set (due to
1568    allocation failure). Otherwise returns FcTrue.
1569
1570 FcObjectSetDestroy
1571
1572 Name
1573
1574    FcObjectSetDestroy -- Destroy an object set
1575
1576 Synopsis
1577
1578 #include <fontconfig/fontconfig.h>
1579
1580    void FcObjectSetDestroy(FcObjectSet *os);
1581
1582 Description
1583
1584    Destroys an object set.
1585
1586 FcObjectSetBuild
1587
1588 Name
1589
1590    FcObjectSetBuild, FcObjectSetVaBuild,
1591    FcObjectSetVapBuild -- Build object set from args
1592
1593 Synopsis
1594
1595 #include <fontconfig/fontconfig.h>
1596
1597    FcObjectSet * FcObjectSetBuild(const char *first, ...);
1598
1599    FcObjectSet * FcObjectSetVaBuild(const char *first, va_list
1600    va);
1601
1602    void FcObjectSetVapBuild(FcObjectSet *result, const char
1603    *first, va_list va);
1604
1605 Description
1606
1607    These build an object set from a null-terminated list of
1608    property names. FcObjectSetVapBuild is a macro version of
1609    FcObjectSetVaBuild which returns the result in the result
1610    variable directly.
1611      __________________________________________________________
1612
1613 FreeType specific functions
1614
1615    Table of Contents
1616    FcFreeTypeCharIndex -- map Unicode to glyph id
1617    FcFreeTypeCharSet -- compute Unicode coverage
1618    FcFreeTypeCharSetAndSpacing -- compute Unicode coverage and
1619           spacing type
1620
1621    FcFreeTypeQuery -- compute pattern from font file (and index)
1622    FcFreeTypeQueryAll -- compute all patterns from font file (and
1623           index)
1624
1625    FcFreeTypeQueryFace -- compute pattern from FT_Face
1626
1627    While the fontconfig library doesn't insist that FreeType be
1628    used as the rasterization mechanism for fonts, it does provide
1629    some convenience functions.
1630
1631 FcFreeTypeCharIndex
1632
1633 Name
1634
1635    FcFreeTypeCharIndex -- map Unicode to glyph id
1636
1637 Synopsis
1638
1639 #include <fontconfig.h>
1640 #include <fcfreetype.h>
1641
1642    FT_UInt FcFreeTypeCharIndex(FT_Face face, FcChar32 ucs4);
1643
1644 Description
1645
1646    Maps a Unicode char to a glyph index. This function uses
1647    information from several possible underlying encoding tables to
1648    work around broken fonts. As a result, this function isn't
1649    designed to be used in performance sensitive areas; results
1650    from this function are intended to be cached by higher level
1651    functions.
1652
1653 FcFreeTypeCharSet
1654
1655 Name
1656
1657    FcFreeTypeCharSet -- compute Unicode coverage
1658
1659 Synopsis
1660
1661 #include <fontconfig.h>
1662 #include <fcfreetype.h>
1663
1664    FcCharSet * FcFreeTypeCharSet(FT_Face face, FcBlanks *blanks);
1665
1666 Description
1667
1668    Scans a FreeType face and returns the set of encoded Unicode
1669    chars. FcBlanks is deprecated, blanks is ignored and accepted
1670    only for compatibility with older code.
1671
1672 FcFreeTypeCharSetAndSpacing
1673
1674 Name
1675
1676    FcFreeTypeCharSetAndSpacing -- compute Unicode coverage and
1677    spacing type
1678
1679 Synopsis
1680
1681 #include <fontconfig.h>
1682 #include <fcfreetype.h>
1683
1684    FcCharSet * FcFreeTypeCharSetAndSpacing(FT_Face face, FcBlanks
1685    *blanks, int *spacing);
1686
1687 Description
1688
1689    Scans a FreeType face and returns the set of encoded Unicode
1690    chars. FcBlanks is deprecated, blanks is ignored and accepted
1691    only for compatibility with older code. spacing receives the
1692    computed spacing type of the font, one of FC_MONO for a font
1693    where all glyphs have the same width, FC_DUAL, where the font
1694    has glyphs in precisely two widths, one twice as wide as the
1695    other, or FC_PROPORTIONAL where the font has glyphs of many
1696    widths.
1697
1698 FcFreeTypeQuery
1699
1700 Name
1701
1702    FcFreeTypeQuery -- compute pattern from font file (and index)
1703
1704 Synopsis
1705
1706 #include <fontconfig.h>
1707 #include <fcfreetype.h>
1708
1709    FcPattern * FcFreeTypeQuery(const FcChar8 *file, int id,
1710    FcBlanks *blanks, int *count);
1711
1712 Description
1713
1714    Constructs a pattern representing the 'id'th face in 'file'.
1715    The number of faces in 'file' is returned in 'count'. FcBlanks
1716    is deprecated, blanks is ignored and accepted only for
1717    compatibility with older code.
1718
1719 FcFreeTypeQueryAll
1720
1721 Name
1722
1723    FcFreeTypeQueryAll -- compute all patterns from font file (and
1724    index)
1725
1726 Synopsis
1727
1728 #include <fontconfig.h>
1729 #include <fcfreetype.h>
1730
1731    unsigned int FcFreeTypeQueryAll(const FcChar8 *file, int id,
1732    FcBlanks *blanks, int *count, FcFontSet *set);
1733
1734 Description
1735
1736    Constructs patterns found in 'file'. If id is -1, then all
1737    patterns found in 'file' are added to 'set'. Otherwise, this
1738    function works exactly like FcFreeTypeQuery(). The number of
1739    faces in 'file' is returned in 'count'. The number of patterns
1740    added to 'set' is returned. FcBlanks is deprecated, blanks is
1741    ignored and accepted only for compatibility with older code.
1742
1743 Since
1744
1745    version 2.12.91
1746
1747 FcFreeTypeQueryFace
1748
1749 Name
1750
1751    FcFreeTypeQueryFace -- compute pattern from FT_Face
1752
1753 Synopsis
1754
1755 #include <fontconfig.h>
1756 #include <fcfreetype.h>
1757
1758    FcPattern * FcFreeTypeQueryFace(const FT_Face face, const
1759    FcChar8 *file, int id, FcBlanks *blanks);
1760
1761 Description
1762
1763    Constructs a pattern representing 'face'. 'file' and 'id' are
1764    used solely as data for pattern elements (FC_FILE, FC_INDEX and
1765    sometimes FC_FAMILY). FcBlanks is deprecated, blanks is ignored
1766    and accepted only for compatibility with older code.
1767      __________________________________________________________
1768
1769 FcValue
1770
1771    Table of Contents
1772    FcValueDestroy -- Free a value
1773    FcValueSave -- Copy a value
1774    FcValuePrint -- Print a value to stdout
1775    FcValueEqual -- Test two values for equality
1776
1777    FcValue is a structure containing a type tag and a union of all
1778    possible datatypes. The tag is an enum of type FcType and is
1779    intended to provide a measure of run-time typechecking,
1780    although that depends on careful programming.
1781
1782 FcValueDestroy
1783
1784 Name
1785
1786    FcValueDestroy -- Free a value
1787
1788 Synopsis
1789
1790 #include <fontconfig/fontconfig.h>
1791
1792    void FcValueDestroy(FcValue v);
1793
1794 Description
1795
1796    Frees any memory referenced by v. Values of type FcTypeString,
1797    FcTypeMatrix and FcTypeCharSet reference memory, the other
1798    types do not.
1799
1800 FcValueSave
1801
1802 Name
1803
1804    FcValueSave -- Copy a value
1805
1806 Synopsis
1807
1808 #include <fontconfig/fontconfig.h>
1809
1810    FcValue FcValueSave(FcValue v);
1811
1812 Description
1813
1814    Returns a copy of v duplicating any object referenced by it so
1815    that v may be safely destroyed without harming the new value.
1816
1817 FcValuePrint
1818
1819 Name
1820
1821    FcValuePrint -- Print a value to stdout
1822
1823 Synopsis
1824
1825 #include <fontconfig/fontconfig.h>
1826
1827    void FcValuePrint(FcValue v);
1828
1829 Description
1830
1831    Prints a human-readable representation of v to stdout. The
1832    format should not be considered part of the library
1833    specification as it may change in the future.
1834
1835 FcValueEqual
1836
1837 Name
1838
1839    FcValueEqual -- Test two values for equality
1840
1841 Synopsis
1842
1843 #include <fontconfig/fontconfig.h>
1844
1845    FcBool FcValueEqual(FcValue v_a, FcValue v_b);
1846
1847 Description
1848
1849    Compares two values. Integers and Doubles are compared as
1850    numbers; otherwise the two values have to be the same type to
1851    be considered equal. Strings are compared ignoring case.
1852      __________________________________________________________
1853
1854 FcCharSet
1855
1856    Table of Contents
1857    FcCharSetCreate -- Create an empty character set
1858    FcCharSetDestroy -- Destroy a character set
1859    FcCharSetAddChar -- Add a character to a charset
1860    FcCharSetDelChar -- Add a character to a charset
1861    FcCharSetCopy -- Copy a charset
1862    FcCharSetEqual -- Compare two charsets
1863    FcCharSetIntersect -- Intersect charsets
1864    FcCharSetUnion -- Add charsets
1865    FcCharSetSubtract -- Subtract charsets
1866    FcCharSetMerge -- Merge charsets
1867    FcCharSetHasChar -- Check a charset for a char
1868    FcCharSetCount -- Count entries in a charset
1869    FcCharSetIntersectCount -- Intersect and count charsets
1870    FcCharSetSubtractCount -- Subtract and count charsets
1871    FcCharSetIsSubset -- Test for charset inclusion
1872    FcCharSetFirstPage -- Start enumerating charset contents
1873    FcCharSetNextPage -- Continue enumerating charset contents
1874    FcCharSetCoverage -- DEPRECATED return coverage for a Unicode
1875           page
1876
1877    FcCharSetNew -- DEPRECATED alias for FcCharSetCreate
1878
1879    An FcCharSet is a boolean array indicating a set of Unicode
1880    chars. Those associated with a font are marked constant and
1881    cannot be edited. FcCharSets may be reference counted
1882    internally to reduce memory consumption; this may be visible to
1883    applications as the result of FcCharSetCopy may return it's
1884    argument, and that CharSet may remain unmodifiable.
1885
1886 FcCharSetCreate
1887
1888 Name
1889
1890    FcCharSetCreate -- Create an empty character set
1891
1892 Synopsis
1893
1894 #include <fontconfig/fontconfig.h>
1895
1896    FcCharSet * FcCharSetCreate(void);
1897
1898 Description
1899
1900    FcCharSetCreate allocates and initializes a new empty character
1901    set object.
1902
1903 FcCharSetDestroy
1904
1905 Name
1906
1907    FcCharSetDestroy -- Destroy a character set
1908
1909 Synopsis
1910
1911 #include <fontconfig/fontconfig.h>
1912
1913    void FcCharSetDestroy(FcCharSet *fcs);
1914
1915 Description
1916
1917    FcCharSetDestroy decrements the reference count fcs. If the
1918    reference count becomes zero, all memory referenced is freed.
1919
1920 FcCharSetAddChar
1921
1922 Name
1923
1924    FcCharSetAddChar -- Add a character to a charset
1925
1926 Synopsis
1927
1928 #include <fontconfig/fontconfig.h>
1929
1930    FcBool FcCharSetAddChar(FcCharSet *fcs, FcChar32 ucs4);
1931
1932 Description
1933
1934    FcCharSetAddChar adds a single Unicode char to the set,
1935    returning FcFalse on failure, either as a result of a constant
1936    set or from running out of memory.
1937
1938 FcCharSetDelChar
1939
1940 Name
1941
1942    FcCharSetDelChar -- Add a character to a charset
1943
1944 Synopsis
1945
1946 #include <fontconfig/fontconfig.h>
1947
1948    FcBool FcCharSetDelChar(FcCharSet *fcs, FcChar32 ucs4);
1949
1950 Description
1951
1952    FcCharSetDelChar deletes a single Unicode char from the set,
1953    returning FcFalse on failure, either as a result of a constant
1954    set or from running out of memory.
1955
1956 Since
1957
1958    version 2.9.0
1959
1960 FcCharSetCopy
1961
1962 Name
1963
1964    FcCharSetCopy -- Copy a charset
1965
1966 Synopsis
1967
1968 #include <fontconfig/fontconfig.h>
1969
1970    FcCharSet * FcCharSetCopy(FcCharSet *src);
1971
1972 Description
1973
1974    Makes a copy of src; note that this may not actually do
1975    anything more than increment the reference count on src.
1976
1977 FcCharSetEqual
1978
1979 Name
1980
1981    FcCharSetEqual -- Compare two charsets
1982
1983 Synopsis
1984
1985 #include <fontconfig/fontconfig.h>
1986
1987    FcBool FcCharSetEqual(const FcCharSet *a, const FcCharSet *b);
1988
1989 Description
1990
1991    Returns whether a and b contain the same set of Unicode chars.
1992
1993 FcCharSetIntersect
1994
1995 Name
1996
1997    FcCharSetIntersect -- Intersect charsets
1998
1999 Synopsis
2000
2001 #include <fontconfig/fontconfig.h>
2002
2003    FcCharSet * FcCharSetIntersect(const FcCharSet *a, const
2004    FcCharSet *b);
2005
2006 Description
2007
2008    Returns a set including only those chars found in both a and b.
2009
2010 FcCharSetUnion
2011
2012 Name
2013
2014    FcCharSetUnion -- Add charsets
2015
2016 Synopsis
2017
2018 #include <fontconfig/fontconfig.h>
2019
2020    FcCharSet * FcCharSetUnion(const FcCharSet *a, const FcCharSet
2021    *b);
2022
2023 Description
2024
2025    Returns a set including only those chars found in either a or
2026    b.
2027
2028 FcCharSetSubtract
2029
2030 Name
2031
2032    FcCharSetSubtract -- Subtract charsets
2033
2034 Synopsis
2035
2036 #include <fontconfig/fontconfig.h>
2037
2038    FcCharSet * FcCharSetSubtract(const FcCharSet *a, const
2039    FcCharSet *b);
2040
2041 Description
2042
2043    Returns a set including only those chars found in a but not b.
2044
2045 FcCharSetMerge
2046
2047 Name
2048
2049    FcCharSetMerge -- Merge charsets
2050
2051 Synopsis
2052
2053 #include <fontconfig/fontconfig.h>
2054
2055    FcBool FcCharSetMerge(FcCharSet *a, const FcCharSet *b, FcBool
2056    *changed);
2057
2058 Description
2059
2060    Adds all chars in b to a. In other words, this is an in-place
2061    version of FcCharSetUnion. If changed is not NULL, then it
2062    returns whether any new chars from b were added to a. Returns
2063    FcFalse on failure, either when a is a constant set or from
2064    running out of memory.
2065
2066 FcCharSetHasChar
2067
2068 Name
2069
2070    FcCharSetHasChar -- Check a charset for a char
2071
2072 Synopsis
2073
2074 #include <fontconfig/fontconfig.h>
2075
2076    FcBool FcCharSetHasChar(const FcCharSet *fcs, FcChar32 ucs4);
2077
2078 Description
2079
2080    Returns whether fcs contains the char ucs4.
2081
2082 FcCharSetCount
2083
2084 Name
2085
2086    FcCharSetCount -- Count entries in a charset
2087
2088 Synopsis
2089
2090 #include <fontconfig/fontconfig.h>
2091
2092    FcChar32 FcCharSetCount(const FcCharSet *a);
2093
2094 Description
2095
2096    Returns the total number of Unicode chars in a.
2097
2098 FcCharSetIntersectCount
2099
2100 Name
2101
2102    FcCharSetIntersectCount -- Intersect and count charsets
2103
2104 Synopsis
2105
2106 #include <fontconfig/fontconfig.h>
2107
2108    FcChar32 FcCharSetIntersectCount(const FcCharSet *a, const
2109    FcCharSet *b);
2110
2111 Description
2112
2113    Returns the number of chars that are in both a and b.
2114
2115 FcCharSetSubtractCount
2116
2117 Name
2118
2119    FcCharSetSubtractCount -- Subtract and count charsets
2120
2121 Synopsis
2122
2123 #include <fontconfig/fontconfig.h>
2124
2125    FcChar32 FcCharSetSubtractCount(const FcCharSet *a, const
2126    FcCharSet *b);
2127
2128 Description
2129
2130    Returns the number of chars that are in a but not in b.
2131
2132 FcCharSetIsSubset
2133
2134 Name
2135
2136    FcCharSetIsSubset -- Test for charset inclusion
2137
2138 Synopsis
2139
2140 #include <fontconfig/fontconfig.h>
2141
2142    FcBool FcCharSetIsSubset(const FcCharSet *a, const FcCharSet
2143    *b);
2144
2145 Description
2146
2147    Returns whether a is a subset of b.
2148
2149 FcCharSetFirstPage
2150
2151 Name
2152
2153    FcCharSetFirstPage -- Start enumerating charset contents
2154
2155 Synopsis
2156
2157 #include <fontconfig/fontconfig.h>
2158
2159    FcChar32 FcCharSetFirstPage(const FcCharSet *a,
2160    FcChar32[FC_CHARSET_MAP_SIZE] map, FcChar32 *next);
2161
2162 Description
2163
2164    Builds an array of bits in map marking the first page of
2165    Unicode coverage of a. *next is set to contains the base code
2166    point for the next page in a. Returns the base code point for
2167    the page, or FC_CHARSET_DONE if a contains no pages. As an
2168    example, if FcCharSetFirstPage returns 0x300 and fills map with
2169 0xffffffff 0xffffffff 0x01000008 0x44300002 0xffffd7f0 0xfffffffb 0xffff
2170 7fff 0xffff0003
2171
2172    Then the page contains code points 0x300 through 0x33f (the
2173    first 64 code points on the page) because map[0] and map[1]
2174    both have all their bits set. It also contains code points
2175    0x343 (0x300 + 32*2 + (4-1)) and 0x35e (0x300 + 32*2 + (31-1))
2176    because map[2] has the 4th and 31st bits set. The code points
2177    represented by map[3] and later are left as an excercise for
2178    the reader ;).
2179
2180 FcCharSetNextPage
2181
2182 Name
2183
2184    FcCharSetNextPage -- Continue enumerating charset contents
2185
2186 Synopsis
2187
2188 #include <fontconfig/fontconfig.h>
2189
2190    FcChar32 FcCharSetNextPage(const FcCharSet *a,
2191    FcChar32[FC_CHARSET_MAP_SIZE] map, FcChar32 *next);
2192
2193 Description
2194
2195    Builds an array of bits in map marking the Unicode coverage of
2196    a for page containing *next (see the FcCharSetFirstPage
2197    description for details). *next is set to contains the base
2198    code point for the next page in a. Returns the base of code
2199    point for the page, or FC_CHARSET_DONE if a does not contain
2200    *next.
2201
2202 FcCharSetCoverage
2203
2204 Name
2205
2206    FcCharSetCoverage -- DEPRECATED return coverage for a Unicode
2207    page
2208
2209 Synopsis
2210
2211 #include <fontconfig/fontconfig.h>
2212
2213    FcChar32 FcCharSetCoverage(const FcCharSet *a, FcChar32page,
2214    FcChar32[8]result);
2215
2216 Description
2217
2218    DEPRECATED This function returns a bitmask in result which
2219    indicates which code points in page are included in a.
2220    FcCharSetCoverage returns the next page in the charset which
2221    has any coverage.
2222
2223 FcCharSetNew
2224
2225 Name
2226
2227    FcCharSetNew -- DEPRECATED alias for FcCharSetCreate
2228
2229 Synopsis
2230
2231 #include <fontconfig/fontconfig.h>
2232
2233    FcCharSet * FcCharSetNew(void);
2234
2235 Description
2236
2237    FcCharSetNew is a DEPRECATED alias for FcCharSetCreate.
2238      __________________________________________________________
2239
2240 FcLangSet
2241
2242    Table of Contents
2243    FcLangSetCreate -- create a langset object
2244    FcLangSetDestroy -- destroy a langset object
2245    FcLangSetCopy -- copy a langset object
2246    FcLangSetAdd -- add a language to a langset
2247    FcLangSetDel -- delete a language from a langset
2248    FcLangSetUnion -- Add langsets
2249    FcLangSetSubtract -- Subtract langsets
2250    FcLangSetCompare -- compare language sets
2251    FcLangSetContains -- check langset subset relation
2252    FcLangSetEqual -- test for matching langsets
2253    FcLangSetHash -- return a hash value for a langset
2254    FcLangSetHasLang -- test langset for language support
2255    FcGetDefaultLangs -- Get the default languages list
2256    FcLangSetGetLangs -- get the list of languages in the langset
2257    FcGetLangs -- Get list of languages
2258    FcLangNormalize -- Normalize the language string
2259    FcLangGetCharSet -- Get character map for a language
2260
2261    An FcLangSet is a set of language names (each of which include
2262    language and an optional territory). They are used when
2263    selecting fonts to indicate which languages the fonts need to
2264    support. Each font is marked, using language orthography
2265    information built into fontconfig, with the set of supported
2266    languages.
2267
2268 FcLangSetCreate
2269
2270 Name
2271
2272    FcLangSetCreate -- create a langset object
2273
2274 Synopsis
2275
2276 #include <fontconfig/fontconfig.h>
2277
2278    FcLangSet * FcLangSetCreate(void);
2279
2280 Description
2281
2282    FcLangSetCreate creates a new FcLangSet object.
2283
2284 FcLangSetDestroy
2285
2286 Name
2287
2288    FcLangSetDestroy -- destroy a langset object
2289
2290 Synopsis
2291
2292 #include <fontconfig/fontconfig.h>
2293
2294    void FcLangSetDestroy(FcLangSet *ls);
2295
2296 Description
2297
2298    FcLangSetDestroy destroys a FcLangSet object, freeing all
2299    memory associated with it.
2300
2301 FcLangSetCopy
2302
2303 Name
2304
2305    FcLangSetCopy -- copy a langset object
2306
2307 Synopsis
2308
2309 #include <fontconfig/fontconfig.h>
2310
2311    FcLangSet * FcLangSetCopy(const FcLangSet *ls);
2312
2313 Description
2314
2315    FcLangSetCopy creates a new FcLangSet object and populates it
2316    with the contents of ls.
2317
2318 FcLangSetAdd
2319
2320 Name
2321
2322    FcLangSetAdd -- add a language to a langset
2323
2324 Synopsis
2325
2326 #include <fontconfig/fontconfig.h>
2327
2328    FcBool FcLangSetAdd(FcLangSet *ls, const FcChar8 *lang);
2329
2330 Description
2331
2332    lang is added to ls. lang should be of the form Ll-Tt where Ll
2333    is a two or three letter language from ISO 639 and Tt is a
2334    territory from ISO 3166.
2335
2336 FcLangSetDel
2337
2338 Name
2339
2340    FcLangSetDel -- delete a language from a langset
2341
2342 Synopsis
2343
2344 #include <fontconfig/fontconfig.h>
2345
2346    FcBool FcLangSetDel(FcLangSet *ls, const FcChar8 *lang);
2347
2348 Description
2349
2350    lang is removed from ls. lang should be of the form Ll-Tt where
2351    Ll is a two or three letter language from ISO 639 and Tt is a
2352    territory from ISO 3166.
2353
2354 Since
2355
2356    version 2.9.0
2357
2358 FcLangSetUnion
2359
2360 Name
2361
2362    FcLangSetUnion -- Add langsets
2363
2364 Synopsis
2365
2366 #include <fontconfig/fontconfig.h>
2367
2368    FcLangSet * FcLangSetUnion(const FcLangSet *ls_a, const
2369    FcLangSet *ls_b);
2370
2371 Description
2372
2373    Returns a set including only those languages found in either
2374    ls_a or ls_b.
2375
2376 Since
2377
2378    version 2.9.0
2379
2380 FcLangSetSubtract
2381
2382 Name
2383
2384    FcLangSetSubtract -- Subtract langsets
2385
2386 Synopsis
2387
2388 #include <fontconfig/fontconfig.h>
2389
2390    FcLangSet * FcLangSetSubtract(const FcLangSet *ls_a, const
2391    FcLangSet *ls_b);
2392
2393 Description
2394
2395    Returns a set including only those languages found in ls_a but
2396    not in ls_b.
2397
2398 Since
2399
2400    version 2.9.0
2401
2402 FcLangSetCompare
2403
2404 Name
2405
2406    FcLangSetCompare -- compare language sets
2407
2408 Synopsis
2409
2410 #include <fontconfig/fontconfig.h>
2411
2412    FcLangResult FcLangSetCompare(const FcLangSet *ls_a, const
2413    FcLangSet *ls_b);
2414
2415 Description
2416
2417    FcLangSetCompare compares language coverage for ls_a and ls_b.
2418    If they share any language and territory pair, this function
2419    returns FcLangEqual. If they share a language but differ in
2420    which territory that language is for, this function returns
2421    FcLangDifferentTerritory. If they share no languages in common,
2422    this function returns FcLangDifferentLang.
2423
2424 FcLangSetContains
2425
2426 Name
2427
2428    FcLangSetContains -- check langset subset relation
2429
2430 Synopsis
2431
2432 #include <fontconfig/fontconfig.h>
2433
2434    FcBool FcLangSetContains(const FcLangSet *ls_a, const FcLangSet
2435    *ls_b);
2436
2437 Description
2438
2439    FcLangSetContains returns FcTrue if ls_a contains every
2440    language in ls_b. ls_a will 'contain' a language from ls_b if
2441    ls_a has exactly the language, or either the language or ls_a
2442    has no territory.
2443
2444 FcLangSetEqual
2445
2446 Name
2447
2448    FcLangSetEqual -- test for matching langsets
2449
2450 Synopsis
2451
2452 #include <fontconfig/fontconfig.h>
2453
2454    FcBool FcLangSetEqual(const FcLangSet *ls_a, const FcLangSet
2455    *ls_b);
2456
2457 Description
2458
2459    Returns FcTrue if and only if ls_a supports precisely the same
2460    language and territory combinations as ls_b.
2461
2462 FcLangSetHash
2463
2464 Name
2465
2466    FcLangSetHash -- return a hash value for a langset
2467
2468 Synopsis
2469
2470 #include <fontconfig/fontconfig.h>
2471
2472    FcChar32 FcLangSetHash(const FcLangSet *ls);
2473
2474 Description
2475
2476    This function returns a value which depends solely on the
2477    languages supported by ls. Any language which equals ls will
2478    have the same result from FcLangSetHash. However, two langsets
2479    with the same hash value may not be equal.
2480
2481 FcLangSetHasLang
2482
2483 Name
2484
2485    FcLangSetHasLang -- test langset for language support
2486
2487 Synopsis
2488
2489 #include <fontconfig/fontconfig.h>
2490
2491    FcLangResult FcLangSetHasLang(const FcLangSet *ls, const
2492    FcChar8 *lang);
2493
2494 Description
2495
2496    FcLangSetHasLang checks whether ls supports lang. If ls has a
2497    matching language and territory pair, this function returns
2498    FcLangEqual. If ls has a matching language but differs in which
2499    territory that language is for, this function returns
2500    FcLangDifferentTerritory. If ls has no matching language, this
2501    function returns FcLangDifferentLang.
2502
2503 FcGetDefaultLangs
2504
2505 Name
2506
2507    FcGetDefaultLangs -- Get the default languages list
2508
2509 Synopsis
2510
2511 #include <fontconfig/fontconfig.h>
2512
2513    FcStrSet * FcGetDefaultLangs(void);
2514
2515 Description
2516
2517    Returns a string set of the default languages according to the
2518    environment variables on the system. This function looks for
2519    them in order of FC_LANG, LC_ALL, LC_CTYPE and LANG then. If
2520    there are no valid values in those environment variables, "en"
2521    will be set as fallback.
2522
2523 Since
2524
2525    version 2.9.91
2526
2527 FcLangSetGetLangs
2528
2529 Name
2530
2531    FcLangSetGetLangs -- get the list of languages in the langset
2532
2533 Synopsis
2534
2535 #include <fontconfig/fontconfig.h>
2536
2537    FcStrSet * FcLangSetGetLangs(const FcLangSet *ls);
2538
2539 Description
2540
2541    Returns a string set of all languages in langset.
2542
2543 FcGetLangs
2544
2545 Name
2546
2547    FcGetLangs -- Get list of languages
2548
2549 Synopsis
2550
2551 #include <fontconfig/fontconfig.h>
2552
2553    FcStrSet * FcGetLangs(void);
2554
2555 Description
2556
2557    Returns a string set of all known languages.
2558
2559 FcLangNormalize
2560
2561 Name
2562
2563    FcLangNormalize -- Normalize the language string
2564
2565 Synopsis
2566
2567 #include <fontconfig/fontconfig.h>
2568
2569    FcChar8 * FcLangNormalize(const FcChar8 *lang);
2570
2571 Description
2572
2573    Returns a string to make lang suitable on fontconfig.
2574
2575 Since
2576
2577    version 2.10.91
2578
2579 FcLangGetCharSet
2580
2581 Name
2582
2583    FcLangGetCharSet -- Get character map for a language
2584
2585 Synopsis
2586
2587 #include <fontconfig/fontconfig.h>
2588
2589    const FcCharSet * FcLangGetCharSet(const FcChar8 *lang);
2590
2591 Description
2592
2593    Returns the FcCharMap for a language.
2594      __________________________________________________________
2595
2596 FcMatrix
2597
2598    Table of Contents
2599    FcMatrixInit -- initialize an FcMatrix structure
2600    FcMatrixCopy -- Copy a matrix
2601    FcMatrixEqual -- Compare two matrices
2602    FcMatrixMultiply -- Multiply matrices
2603    FcMatrixRotate -- Rotate a matrix
2604    FcMatrixScale -- Scale a matrix
2605    FcMatrixShear -- Shear a matrix
2606
2607    FcMatrix structures hold an affine transformation in matrix
2608    form.
2609
2610 FcMatrixInit
2611
2612 Name
2613
2614    FcMatrixInit -- initialize an FcMatrix structure
2615
2616 Synopsis
2617
2618 #include <fontconfig/fontconfig.h>
2619
2620    void FcMatrixInit(FcMatrix *matrix);
2621
2622 Description
2623
2624    FcMatrixInit initializes matrix to the identity matrix.
2625
2626 FcMatrixCopy
2627
2628 Name
2629
2630    FcMatrixCopy -- Copy a matrix
2631
2632 Synopsis
2633
2634 #include <fontconfig/fontconfig.h>
2635
2636    void FcMatrixCopy(const FcMatrix *matrix);
2637
2638 Description
2639
2640    FcMatrixCopy allocates a new FcMatrix and copies mat into it.
2641
2642 FcMatrixEqual
2643
2644 Name
2645
2646    FcMatrixEqual -- Compare two matrices
2647
2648 Synopsis
2649
2650 #include <fontconfig/fontconfig.h>
2651
2652    void FcMatrixEqual(const FcMatrix *matrix1, const FcMatrix
2653    *matrix2);
2654
2655 Description
2656
2657    FcMatrixEqual compares matrix1 and matrix2 returning FcTrue
2658    when they are equal and FcFalse when they are not.
2659
2660 FcMatrixMultiply
2661
2662 Name
2663
2664    FcMatrixMultiply -- Multiply matrices
2665
2666 Synopsis
2667
2668 #include <fontconfig/fontconfig.h>
2669
2670    void FcMatrixMultiply(FcMatrix *result, const FcMatrix
2671    *matrix1, const FcMatrix *matrix2);
2672
2673 Description
2674
2675    FcMatrixMultiply multiplies matrix1 and matrix2 storing the
2676    result in result.
2677
2678 FcMatrixRotate
2679
2680 Name
2681
2682    FcMatrixRotate -- Rotate a matrix
2683
2684 Synopsis
2685
2686 #include <fontconfig/fontconfig.h>
2687
2688    void FcMatrixRotate(FcMatrix *matrix, double cos, double sin);
2689
2690 Description
2691
2692    FcMatrixRotate rotates matrix by the angle who's sine is sin
2693    and cosine is cos. This is done by multiplying by the matrix:
2694   cos -sin
2695   sin  cos
2696
2697 FcMatrixScale
2698
2699 Name
2700
2701    FcMatrixScale -- Scale a matrix
2702
2703 Synopsis
2704
2705 #include <fontconfig/fontconfig.h>
2706
2707    void FcMatrixScale(FcMatrix *matrix, double sx, double dy);
2708
2709 Description
2710
2711    FcMatrixScale multiplies matrix x values by sx and y values by
2712    dy. This is done by multiplying by the matrix:
2713    sx  0
2714    0   dy
2715
2716 FcMatrixShear
2717
2718 Name
2719
2720    FcMatrixShear -- Shear a matrix
2721
2722 Synopsis
2723
2724 #include <fontconfig/fontconfig.h>
2725
2726    void FcMatrixShear(FcMatrix *matrix, double sh, double sv);
2727
2728 Description
2729
2730    FcMatrixShare shears matrix horizontally by sh and vertically
2731    by sv. This is done by multiplying by the matrix:
2732   1  sh
2733   sv  1
2734      __________________________________________________________
2735
2736 FcRange
2737
2738    Table of Contents
2739    FcRangeCopy -- Copy a range object
2740    FcRangeCreateDouble -- create a range object for double
2741    FcRangeCreateInteger -- create a range object for integer
2742    FcRangeDestroy -- destroy a range object
2743    FcRangeGetDouble -- Get the range in double
2744
2745    An FcRange holds two variables to indicate a range in between.
2746
2747 FcRangeCopy
2748
2749 Name
2750
2751    FcRangeCopy -- Copy a range object
2752
2753 Synopsis
2754
2755 #include <fontconfig/fontconfig.h>
2756
2757    FcRange * FcRangeCopy(const FcRange *range);
2758
2759 Description
2760
2761    FcRangeCopy creates a new FcRange object and populates it with
2762    the contents of range.
2763
2764 Since
2765
2766    version 2.11.91
2767
2768 FcRangeCreateDouble
2769
2770 Name
2771
2772    FcRangeCreateDouble -- create a range object for double
2773
2774 Synopsis
2775
2776 #include <fontconfig/fontconfig.h>
2777
2778    FcRange * FcRangeCreateDouble(doublebegin, doubleend);
2779
2780 Description
2781
2782    FcRangeCreateDouble creates a new FcRange object with double
2783    sized value.
2784
2785 Since
2786
2787    version 2.11.91
2788
2789 FcRangeCreateInteger
2790
2791 Name
2792
2793    FcRangeCreateInteger -- create a range object for integer
2794
2795 Synopsis
2796
2797 #include <fontconfig/fontconfig.h>
2798
2799    FcRange * FcRangeCreateInteger(intbegin, intend);
2800
2801 Description
2802
2803    FcRangeCreateInteger creates a new FcRange object with integer
2804    sized value.
2805
2806 Since
2807
2808    version 2.11.91
2809
2810 FcRangeDestroy
2811
2812 Name
2813
2814    FcRangeDestroy -- destroy a range object
2815
2816 Synopsis
2817
2818 #include <fontconfig/fontconfig.h>
2819
2820    void FcRangeDestroy(FcRange *range);
2821
2822 Description
2823
2824    FcRangeDestroy destroys a FcRange object, freeing all memory
2825    associated with it.
2826
2827 Since
2828
2829    version 2.11.91
2830
2831 FcRangeGetDouble
2832
2833 Name
2834
2835    FcRangeGetDouble -- Get the range in double
2836
2837 Synopsis
2838
2839 #include <fontconfig/fontconfig.h>
2840
2841    FcBool FcRangeGetDouble(const FcRange *range, double *begin,
2842    double *end);
2843
2844 Description
2845
2846    Returns in begin and end as the range.
2847
2848 Since
2849
2850    version 2.11.91
2851      __________________________________________________________
2852
2853 FcConfig
2854
2855    Table of Contents
2856    FcConfigCreate -- Create a configuration
2857    FcConfigReference -- Increment config reference count
2858    FcConfigDestroy -- Destroy a configuration
2859    FcConfigSetCurrent -- Set configuration as default
2860    FcConfigGetCurrent -- Return current configuration
2861    FcConfigUptoDate -- Check timestamps on config files
2862    FcConfigHome -- return the current home directory.
2863    FcConfigEnableHome -- controls use of the home directory.
2864    FcConfigBuildFonts -- Build font database
2865    FcConfigGetConfigDirs -- Get config directories
2866    FcConfigGetFontDirs -- Get font directories
2867    FcConfigGetConfigFiles -- Get config files
2868    FcConfigGetCache -- DEPRECATED used to return per-user cache
2869           filename
2870
2871    FcConfigGetCacheDirs -- return the list of directories searched
2872           for cache files
2873
2874    FcConfigGetFonts -- Get config font set
2875    FcConfigGetBlanks -- Get config blanks
2876    FcConfigGetRescanInterval -- Get config rescan interval
2877    FcConfigSetRescanInterval -- Set config rescan interval
2878    FcConfigAppFontAddFile -- Add font file to font database
2879    FcConfigAppFontAddDir -- Add fonts from directory to font
2880           database
2881
2882    FcConfigAppFontClear -- Remove all app fonts from font database
2883    FcConfigSubstituteWithPat -- Execute substitutions
2884    FcConfigSubstitute -- Execute substitutions
2885    FcFontMatch -- Return best font
2886    FcFontSort -- Return list of matching fonts
2887    FcFontRenderPrepare -- Prepare pattern for loading font file
2888    FcFontList -- List fonts
2889    FcConfigFilename -- Find a config file
2890    FcConfigParseAndLoad -- load a configuration file
2891    FcConfigParseAndLoadFromMemory -- load a configuration from
2892           memory
2893
2894    FcConfigGetSysRoot -- Obtain the system root directory
2895    FcConfigSetSysRoot -- Set the system root directory
2896    FcConfigFileInfoIterInit -- Initialize the iterator
2897    FcConfigFileInfoIterNext -- Set the iterator to point to the
2898           next list
2899
2900    FcConfigFileInfoIterGet -- Obtain the configuration file
2901           information
2902
2903    An FcConfig object holds the internal representation of a
2904    configuration. There is a default configuration which
2905    applications may use by passing 0 to any function using the
2906    data within an FcConfig.
2907
2908 FcConfigCreate
2909
2910 Name
2911
2912    FcConfigCreate -- Create a configuration
2913
2914 Synopsis
2915
2916 #include <fontconfig/fontconfig.h>
2917
2918    FcConfig * FcConfigCreate(void);
2919
2920 Description
2921
2922    Creates an empty configuration.
2923
2924 FcConfigReference
2925
2926 Name
2927
2928    FcConfigReference -- Increment config reference count
2929
2930 Synopsis
2931
2932 #include <fontconfig/fontconfig.h>
2933
2934    FcConfig * FcConfigReference(FcConfig *config);
2935
2936 Description
2937
2938    Add another reference to config. Configs are freed only when
2939    the reference count reaches zero. If config is NULL, the
2940    current configuration is used. In that case this function will
2941    be similar to FcConfigGetCurrent() except that it increments
2942    the reference count before returning and the user is
2943    responsible for destroying the configuration when not needed
2944    anymore.
2945
2946 FcConfigDestroy
2947
2948 Name
2949
2950    FcConfigDestroy -- Destroy a configuration
2951
2952 Synopsis
2953
2954 #include <fontconfig/fontconfig.h>
2955
2956    void FcConfigDestroy(FcConfig *config);
2957
2958 Description
2959
2960    Decrements the config reference count. If all references are
2961    gone, destroys the configuration and any data associated with
2962    it. Note that calling this function with the return from
2963    FcConfigGetCurrent will cause a new configuration to be created
2964    for use as current configuration.
2965
2966 FcConfigSetCurrent
2967
2968 Name
2969
2970    FcConfigSetCurrent -- Set configuration as default
2971
2972 Synopsis
2973
2974 #include <fontconfig/fontconfig.h>
2975
2976    FcBool FcConfigSetCurrent(FcConfig *config);
2977
2978 Description
2979
2980    Sets the current default configuration to config. Implicitly
2981    calls FcConfigBuildFonts if necessary, and FcConfigReference()
2982    to inrease the reference count in config since 2.12.0,
2983    returning FcFalse if that call fails.
2984
2985 FcConfigGetCurrent
2986
2987 Name
2988
2989    FcConfigGetCurrent -- Return current configuration
2990
2991 Synopsis
2992
2993 #include <fontconfig/fontconfig.h>
2994
2995    FcConfig * FcConfigGetCurrent(void);
2996
2997 Description
2998
2999    Returns the current default configuration.
3000
3001 FcConfigUptoDate
3002
3003 Name
3004
3005    FcConfigUptoDate -- Check timestamps on config files
3006
3007 Synopsis
3008
3009 #include <fontconfig/fontconfig.h>
3010
3011    FcBool FcConfigUptoDate(FcConfig *config);
3012
3013 Description
3014
3015    Checks all of the files related to config and returns whether
3016    any of them has been modified since the configuration was
3017    created. If config is NULL, the current configuration is used.
3018
3019 FcConfigHome
3020
3021 Name
3022
3023    FcConfigHome -- return the current home directory.
3024
3025 Synopsis
3026
3027 #include <fontconfig/fontconfig.h>
3028
3029    FcChar8 * FcConfigHome(void);
3030
3031 Description
3032
3033    Return the current user's home directory, if it is available,
3034    and if using it is enabled, and NULL otherwise. See also
3035    FcConfigEnableHome).
3036
3037 FcConfigEnableHome
3038
3039 Name
3040
3041    FcConfigEnableHome -- controls use of the home directory.
3042
3043 Synopsis
3044
3045 #include <fontconfig/fontconfig.h>
3046
3047    FcBool FcConfigEnableHome(FcBool enable);
3048
3049 Description
3050
3051    If enable is FcTrue, then Fontconfig will use various files
3052    which are specified relative to the user's home directory
3053    (using the ~ notation in the configuration). When enable is
3054    FcFalse, then all use of the home directory in these contexts
3055    will be disabled. The previous setting of the value is
3056    returned.
3057
3058 FcConfigBuildFonts
3059
3060 Name
3061
3062    FcConfigBuildFonts -- Build font database
3063
3064 Synopsis
3065
3066 #include <fontconfig/fontconfig.h>
3067
3068    FcBool FcConfigBuildFonts(FcConfig *config);
3069
3070 Description
3071
3072    Builds the set of available fonts for the given configuration.
3073    Note that any changes to the configuration after this call have
3074    indeterminate effects. Returns FcFalse if this operation runs
3075    out of memory. If config is NULL, the current configuration is
3076    used.
3077
3078 FcConfigGetConfigDirs
3079
3080 Name
3081
3082    FcConfigGetConfigDirs -- Get config directories
3083
3084 Synopsis
3085
3086 #include <fontconfig/fontconfig.h>
3087
3088    FcStrList * FcConfigGetConfigDirs(FcConfig *config);
3089
3090 Description
3091
3092    Returns the list of font directories specified in the
3093    configuration files for config. Does not include any
3094    subdirectories. If config is NULL, the current configuration is
3095    used.
3096
3097 FcConfigGetFontDirs
3098
3099 Name
3100
3101    FcConfigGetFontDirs -- Get font directories
3102
3103 Synopsis
3104
3105 #include <fontconfig/fontconfig.h>
3106
3107    FcStrList * FcConfigGetFontDirs(FcConfig *config);
3108
3109 Description
3110
3111    Returns the list of font directories in config. This includes
3112    the configured font directories along with any directories
3113    below those in the filesystem. If config is NULL, the current
3114    configuration is used.
3115
3116 FcConfigGetConfigFiles
3117
3118 Name
3119
3120    FcConfigGetConfigFiles -- Get config files
3121
3122 Synopsis
3123
3124 #include <fontconfig/fontconfig.h>
3125
3126    FcStrList * FcConfigGetConfigFiles(FcConfig *config);
3127
3128 Description
3129
3130    Returns the list of known configuration files used to generate
3131    config. If config is NULL, the current configuration is used.
3132
3133 FcConfigGetCache
3134
3135 Name
3136
3137    FcConfigGetCache -- DEPRECATED used to return per-user cache
3138    filename
3139
3140 Synopsis
3141
3142 #include <fontconfig/fontconfig.h>
3143
3144    FcChar8 * FcConfigGetCache(FcConfig *config);
3145
3146 Description
3147
3148    With fontconfig no longer using per-user cache files, this
3149    function now simply returns NULL to indicate that no per-user
3150    file exists.
3151
3152 FcConfigGetCacheDirs
3153
3154 Name
3155
3156    FcConfigGetCacheDirs -- return the list of directories searched
3157    for cache files
3158
3159 Synopsis
3160
3161 #include <fontconfig/fontconfig.h>
3162
3163    FcStrList * FcConfigGetCacheDirs(const FcConfig *config);
3164
3165 Description
3166
3167    FcConfigGetCacheDirs returns a string list containing all of
3168    the directories that fontconfig will search when attempting to
3169    load a cache file for a font directory. If config is NULL, the
3170    current configuration is used.
3171
3172 FcConfigGetFonts
3173
3174 Name
3175
3176    FcConfigGetFonts -- Get config font set
3177
3178 Synopsis
3179
3180 #include <fontconfig/fontconfig.h>
3181
3182    FcFontSet * FcConfigGetFonts(FcConfig *config, FcSetName set);
3183
3184 Description
3185
3186    Returns one of the two sets of fonts from the configuration as
3187    specified by set. This font set is owned by the library and
3188    must not be modified or freed. If config is NULL, the current
3189    configuration is used.
3190
3191 FcConfigGetBlanks
3192
3193 Name
3194
3195    FcConfigGetBlanks -- Get config blanks
3196
3197 Synopsis
3198
3199 #include <fontconfig/fontconfig.h>
3200
3201    FcBlanks * FcConfigGetBlanks(FcConfig *config);
3202
3203 Description
3204
3205    FcBlanks is deprecated. This function always returns NULL.
3206
3207 FcConfigGetRescanInterval
3208
3209 Name
3210
3211    FcConfigGetRescanInterval -- Get config rescan interval
3212
3213 Synopsis
3214
3215 #include <fontconfig/fontconfig.h>
3216
3217    int FcConfigGetRescanInterval(FcConfig *config);
3218
3219 Description
3220
3221    Returns the interval between automatic checks of the
3222    configuration (in seconds) specified in config. The
3223    configuration is checked during a call to FcFontList when this
3224    interval has passed since the last check. An interval setting
3225    of zero disables automatic checks. If config is NULL, the
3226    current configuration is used.
3227
3228 FcConfigSetRescanInterval
3229
3230 Name
3231
3232    FcConfigSetRescanInterval -- Set config rescan interval
3233
3234 Synopsis
3235
3236 #include <fontconfig/fontconfig.h>
3237
3238    FcBool FcConfigSetRescanInterval(FcConfig *config, int
3239    rescanInterval);
3240
3241 Description
3242
3243    Sets the rescan interval. Returns FcFalse if the interval
3244    cannot be set (due to allocation failure). Otherwise returns
3245    FcTrue. An interval setting of zero disables automatic checks.
3246    If config is NULL, the current configuration is used.
3247
3248 FcConfigAppFontAddFile
3249
3250 Name
3251
3252    FcConfigAppFontAddFile -- Add font file to font database
3253
3254 Synopsis
3255
3256 #include <fontconfig/fontconfig.h>
3257
3258    FcBool FcConfigAppFontAddFile(FcConfig *config, const FcChar8
3259    *file);
3260
3261 Description
3262
3263    Adds an application-specific font to the configuration. Returns
3264    FcFalse if the fonts cannot be added (due to allocation failure
3265    or no fonts found). Otherwise returns FcTrue. If config is
3266    NULL, the current configuration is used.
3267
3268 FcConfigAppFontAddDir
3269
3270 Name
3271
3272    FcConfigAppFontAddDir -- Add fonts from directory to font
3273    database
3274
3275 Synopsis
3276
3277 #include <fontconfig/fontconfig.h>
3278
3279    FcBool FcConfigAppFontAddDir(FcConfig *config, const FcChar8
3280    *dir);
3281
3282 Description
3283
3284    Scans the specified directory for fonts, adding each one found
3285    to the application-specific set of fonts. Returns FcFalse if
3286    the fonts cannot be added (due to allocation failure).
3287    Otherwise returns FcTrue. If config is NULL, the current
3288    configuration is used.
3289
3290 FcConfigAppFontClear
3291
3292 Name
3293
3294    FcConfigAppFontClear -- Remove all app fonts from font database
3295
3296 Synopsis
3297
3298 #include <fontconfig/fontconfig.h>
3299
3300    void FcConfigAppFontClear(FcConfig *config);
3301
3302 Description
3303
3304    Clears the set of application-specific fonts. If config is
3305    NULL, the current configuration is used.
3306
3307 FcConfigSubstituteWithPat
3308
3309 Name
3310
3311    FcConfigSubstituteWithPat -- Execute substitutions
3312
3313 Synopsis
3314
3315 #include <fontconfig/fontconfig.h>
3316
3317    FcBool FcConfigSubstituteWithPat(FcConfig *config, FcPattern
3318    *p, FcPattern *p_pat, FcMatchKind kind);
3319
3320 Description
3321
3322    Performs the sequence of pattern modification operations, if
3323    kind is FcMatchPattern, then those tagged as pattern operations
3324    are applied, else if kind is FcMatchFont, those tagged as font
3325    operations are applied and p_pat is used for <test> elements
3326    with target=pattern. Returns FcFalse if the substitution cannot
3327    be performed (due to allocation failure). Otherwise returns
3328    FcTrue. If config is NULL, the current configuration is used.
3329
3330 FcConfigSubstitute
3331
3332 Name
3333
3334    FcConfigSubstitute -- Execute substitutions
3335
3336 Synopsis
3337
3338 #include <fontconfig/fontconfig.h>
3339
3340    FcBool FcConfigSubstitute(FcConfig *config, FcPattern *p,
3341    FcMatchKind kind);
3342
3343 Description
3344
3345    Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns
3346    FcFalse if the substitution cannot be performed (due to
3347    allocation failure). Otherwise returns FcTrue. If config is
3348    NULL, the current configuration is used.
3349
3350 FcFontMatch
3351
3352 Name
3353
3354    FcFontMatch -- Return best font
3355
3356 Synopsis
3357
3358 #include <fontconfig/fontconfig.h>
3359
3360    FcPattern * FcFontMatch(FcConfig *config, FcPattern *p,
3361    FcResult *result);
3362
3363 Description
3364
3365    Finds the font in sets most closely matching pattern and
3366    returns the result of FcFontRenderPrepare for that font and the
3367    provided pattern. This function should be called only after
3368    FcConfigSubstitute and FcDefaultSubstitute have been called for
3369    p; otherwise the results will not be correct. If config is
3370    NULL, the current configuration is used.
3371
3372 FcFontSort
3373
3374 Name
3375
3376    FcFontSort -- Return list of matching fonts
3377
3378 Synopsis
3379
3380 #include <fontconfig/fontconfig.h>
3381
3382    FcFontSet * FcFontSort(FcConfig *config, FcPattern *p, FcBool
3383    trim, FcCharSet **csp, FcResult *result);
3384
3385 Description
3386
3387    Returns the list of fonts sorted by closeness to p. If trim is
3388    FcTrue, elements in the list which don't include Unicode
3389    coverage not provided by earlier elements in the list are
3390    elided. The union of Unicode coverage of all of the fonts is
3391    returned in csp, if csp is not NULL. This function should be
3392    called only after FcConfigSubstitute and FcDefaultSubstitute
3393    have been called for p; otherwise the results will not be
3394    correct.
3395
3396    The returned FcFontSet references FcPattern structures which
3397    may be shared by the return value from multiple FcFontSort
3398    calls, applications must not modify these patterns. Instead,
3399    they should be passed, along with p to FcFontRenderPrepare
3400    which combines them into a complete pattern.
3401
3402    The FcFontSet returned by FcFontSort is destroyed by calling
3403    FcFontSetDestroy. If config is NULL, the current configuration
3404    is used.
3405
3406 FcFontRenderPrepare
3407
3408 Name
3409
3410    FcFontRenderPrepare -- Prepare pattern for loading font file
3411
3412 Synopsis
3413
3414 #include <fontconfig/fontconfig.h>
3415
3416    FcPattern * FcFontRenderPrepare(FcConfig *config, FcPattern
3417    *pat, FcPattern *font);
3418
3419 Description
3420
3421    Creates a new pattern consisting of elements of font not
3422    appearing in pat, elements of pat not appearing in font and the
3423    best matching value from pat for elements appearing in both.
3424    The result is passed to FcConfigSubstituteWithPat with kind
3425    FcMatchFont and then returned.
3426
3427 FcFontList
3428
3429 Name
3430
3431    FcFontList -- List fonts
3432
3433 Synopsis
3434
3435 #include <fontconfig/fontconfig.h>
3436
3437    FcFontSet * FcFontList(FcConfig *config, FcPattern *p,
3438    FcObjectSet *os);
3439
3440 Description
3441
3442    Selects fonts matching p, creates patterns from those fonts
3443    containing only the objects in os and returns the set of unique
3444    such patterns. If config is NULL, the default configuration is
3445    checked to be up to date, and used.
3446
3447 FcConfigFilename
3448
3449 Name
3450
3451    FcConfigFilename -- Find a config file
3452
3453 Synopsis
3454
3455 #include <fontconfig/fontconfig.h>
3456
3457    FcChar8 * FcConfigFilename(const FcChar8 *name);
3458
3459 Description
3460
3461    Given the specified external entity name, return the associated
3462    filename. This provides applications a way to convert various
3463    configuration file references into filename form.
3464
3465    A null or empty name indicates that the default configuration
3466    file should be used; which file this references can be
3467    overridden with the FONTCONFIG_FILE environment variable. Next,
3468    if the name starts with ~, it refers to a file in the current
3469    users home directory. Otherwise if the name doesn't start with
3470    '/', it refers to a file in the default configuration
3471    directory; the built-in default directory can be overridden
3472    with the FONTCONFIG_PATH environment variable.
3473
3474 FcConfigParseAndLoad
3475
3476 Name
3477
3478    FcConfigParseAndLoad -- load a configuration file
3479
3480 Synopsis
3481
3482 #include <fontconfig/fontconfig.h>
3483
3484    FcBool FcConfigParseAndLoad(FcConfig *config, const FcChar8
3485    *file, FcBool complain);
3486
3487 Description
3488
3489    Walks the configuration in 'file' and constructs the internal
3490    representation in 'config'. Any include files referenced from
3491    within 'file' will be loaded and parsed. If 'complain' is
3492    FcFalse, no warning will be displayed if 'file' does not exist.
3493    Error and warning messages will be output to stderr. Returns
3494    FcFalse if some error occurred while loading the file, either a
3495    parse error, semantic error or allocation failure. Otherwise
3496    returns FcTrue.
3497
3498 FcConfigParseAndLoadFromMemory
3499
3500 Name
3501
3502    FcConfigParseAndLoadFromMemory -- load a configuration from
3503    memory
3504
3505 Synopsis
3506
3507 #include <fontconfig/fontconfig.h>
3508
3509    FcBool FcConfigParseAndLoadFromMemory(FcConfig *config, const
3510    FcChar8 *buffer, FcBool complain);
3511
3512 Description
3513
3514    Walks the configuration in 'memory' and constructs the internal
3515    representation in 'config'. Any includes files referenced from
3516    within 'memory' will be loaded and dparsed. If 'complain' is
3517    FcFalse, no warning will be displayed if 'file' does not exist.
3518    Error and warning messages will be output to stderr. Returns
3519    FcFalse if fsome error occurred while loading the file, either
3520    a parse error, semantic error or allocation failure. Otherwise
3521    returns FcTrue.
3522
3523 Since
3524
3525    version 2.12.5
3526
3527 FcConfigGetSysRoot
3528
3529 Name
3530
3531    FcConfigGetSysRoot -- Obtain the system root directory
3532
3533 Synopsis
3534
3535 #include <fontconfig/fontconfig.h>
3536
3537    const FcChar8 * FcConfigGetSysRoot(const FcConfig *config);
3538
3539 Description
3540
3541    Obtrains the system root directory in 'config' if available.
3542
3543 Since
3544
3545    version 2.10.92
3546
3547 FcConfigSetSysRoot
3548
3549 Name
3550
3551    FcConfigSetSysRoot -- Set the system root directory
3552
3553 Synopsis
3554
3555 #include <fontconfig/fontconfig.h>
3556
3557    void FcConfigSetSysRoot(FcConfig *config, const FcChar8
3558    *sysroot);
3559
3560 Description
3561
3562    Set 'sysroot' as the system root directory. fontconfig prepend
3563    'sysroot' to the cache directories in order to allow people to
3564    generate caches at the build time. Note that this causes
3565    changing current config. i.e. this function calls
3566    FcConfigSetCurrent() internally.
3567
3568 Since
3569
3570    version 2.10.92
3571
3572 FcConfigFileInfoIterInit
3573
3574 Name
3575
3576    FcConfigFileInfoIterInit -- Initialize the iterator
3577
3578 Synopsis
3579
3580 #include <fontconfig/fontconfig.h>
3581
3582    void FcConfigFileInfoIterInit(FcConfig *config,
3583    FcConfigFileInfoIter *iter);
3584
3585 Description
3586
3587    Initialize 'iter' with the first iterator in the config file
3588    information list.
3589
3590 Since
3591
3592    version 2.12.91
3593
3594 FcConfigFileInfoIterNext
3595
3596 Name
3597
3598    FcConfigFileInfoIterNext -- Set the iterator to point to the
3599    next list
3600
3601 Synopsis
3602
3603 #include <fontconfig/fontconfig.h>
3604
3605    FcBool FcConfigFileInfoIterNext(FcConfig *config,
3606    FcConfigFileInfoIter *iter);
3607
3608 Description
3609
3610    Set 'iter' to point to the next node in the config file
3611    information list. If there is no next node, FcFalse is
3612    returned.
3613
3614 Since
3615
3616    version 2.12.91
3617
3618 FcConfigFileInfoIterGet
3619
3620 Name
3621
3622    FcConfigFileInfoIterGet -- Obtain the configuration file
3623    information
3624
3625 Synopsis
3626
3627 #include <fontconfig/fontconfig.h>
3628
3629    FcBool FcConfigFileInfoIterGet(FcConfig *config,
3630    FcConfigFileInfoIter *iter, FcChar8 **name, FcChar8
3631    **description, FcBool *enabled);
3632
3633 Description
3634
3635    Obtain the filename, the description and the flag whether it is
3636    enabled or not for 'iter' where points to current configuration
3637    file information. If the iterator is invalid, FcFalse is
3638    returned.
3639
3640 Since
3641
3642    version 2.12.91
3643      __________________________________________________________
3644
3645 FcObjectType
3646
3647    Table of Contents
3648    FcNameRegisterObjectTypes -- Register object types
3649    FcNameUnregisterObjectTypes -- Unregister object types
3650    FcNameGetObjectType -- Lookup an object type
3651
3652    Provides for application-specified font name object types so
3653    that new pattern elements can be generated from font names.
3654
3655 FcNameRegisterObjectTypes
3656
3657 Name
3658
3659    FcNameRegisterObjectTypes -- Register object types
3660
3661 Synopsis
3662
3663 #include <fontconfig/fontconfig.h>
3664
3665    FcBool FcNameRegisterObjectTypes(const FcObjectType *types, int
3666    ntype);
3667
3668 Description
3669
3670    Deprecated. Does nothing. Returns FcFalse.
3671
3672 FcNameUnregisterObjectTypes
3673
3674 Name
3675
3676    FcNameUnregisterObjectTypes -- Unregister object types
3677
3678 Synopsis
3679
3680 #include <fontconfig/fontconfig.h>
3681
3682    FcBool FcNameUnregisterObjectTypes(const FcObjectType *types,
3683    int ntype);
3684
3685 Description
3686
3687    Deprecated. Does nothing. Returns FcFalse.
3688
3689 FcNameGetObjectType
3690
3691 Name
3692
3693    FcNameGetObjectType -- Lookup an object type
3694
3695 Synopsis
3696
3697 #include <fontconfig/fontconfig.h>
3698
3699    const FcObjectType * FcNameGetObjectType(const char *object);
3700
3701 Description
3702
3703    Return the object type for the pattern element named object.
3704      __________________________________________________________
3705
3706 FcConstant
3707
3708    Table of Contents
3709    FcNameRegisterConstants -- Register symbolic constants
3710    FcNameUnregisterConstants -- Unregister symbolic constants
3711    FcNameGetConstant -- Lookup symbolic constant
3712    FcNameConstant -- Get the value for a symbolic constant
3713
3714    Provides for application-specified symbolic constants for font
3715    names.
3716
3717 FcNameRegisterConstants
3718
3719 Name
3720
3721    FcNameRegisterConstants -- Register symbolic constants
3722
3723 Synopsis
3724
3725 #include <fontconfig/fontconfig.h>
3726
3727    FcBool FcNameRegisterConstants(const FcConstant *consts, int
3728    nconsts);
3729
3730 Description
3731
3732    Deprecated. Does nothing. Returns FcFalse.
3733
3734 FcNameUnregisterConstants
3735
3736 Name
3737
3738    FcNameUnregisterConstants -- Unregister symbolic constants
3739
3740 Synopsis
3741
3742 #include <fontconfig/fontconfig.h>
3743
3744    FcBool FcNameUnregisterConstants(const FcConstant *consts, int
3745    nconsts);
3746
3747 Description
3748
3749    Deprecated. Does nothing. Returns FcFalse.
3750
3751 FcNameGetConstant
3752
3753 Name
3754
3755    FcNameGetConstant -- Lookup symbolic constant
3756
3757 Synopsis
3758
3759 #include <fontconfig/fontconfig.h>
3760
3761    const FcConstant * FcNameGetConstant(FcChar8 *string);
3762
3763 Description
3764
3765    Return the FcConstant structure related to symbolic constant
3766    string.
3767
3768 FcNameConstant
3769
3770 Name
3771
3772    FcNameConstant -- Get the value for a symbolic constant
3773
3774 Synopsis
3775
3776 #include <fontconfig/fontconfig.h>
3777
3778    FcBool FcNameConstant(FcChar8 *string, int *result);
3779
3780 Description
3781
3782    Returns whether a symbolic constant with name string is
3783    registered, placing the value of the constant in result if
3784    present.
3785      __________________________________________________________
3786
3787 FcWeight
3788
3789    Table of Contents
3790    FcWeightFromOpenTypeDouble -- Convert from OpenType weight
3791           values to fontconfig ones
3792
3793    FcWeightToOpenTypeDouble -- Convert from fontconfig weight
3794           values to OpenType ones
3795
3796    FcWeightFromOpenType -- Convert from OpenType weight values to
3797           fontconfig ones
3798
3799    FcWeightToOpenType -- Convert from fontconfig weight values to
3800           OpenType ones
3801
3802    Maps weights to and from OpenType weights.
3803
3804 FcWeightFromOpenTypeDouble
3805
3806 Name
3807
3808    FcWeightFromOpenTypeDouble -- Convert from OpenType weight
3809    values to fontconfig ones
3810
3811 Synopsis
3812
3813 #include <fontconfig/fontconfig.h>
3814
3815    double FcWeightFromOpenTypeDouble(doubleot_weight);
3816
3817 Description
3818
3819    FcWeightFromOpenTypeDouble returns an double value to use with
3820    FC_WEIGHT, from an double in the 1..1000 range, resembling the
3821    numbers from OpenType specification's OS/2 usWeight numbers,
3822    which are also similar to CSS font-weight numbers. If input is
3823    negative, zero, or greater than 1000, returns -1. This function
3824    linearly doubleerpolates between various FC_WEIGHT_* constants.
3825    As such, the returned value does not necessarily match any of
3826    the predefined constants.
3827
3828 Since
3829
3830    version 2.12.92
3831
3832 FcWeightToOpenTypeDouble
3833
3834 Name
3835
3836    FcWeightToOpenTypeDouble -- Convert from fontconfig weight
3837    values to OpenType ones
3838
3839 Synopsis
3840
3841 #include <fontconfig/fontconfig.h>
3842
3843    double FcWeightToOpenTypeDouble(doubleot_weight);
3844
3845 Description
3846
3847    FcWeightToOpenTypeDouble is the inverse of
3848    FcWeightFromOpenType. If the input is less than FC_WEIGHT_THIN
3849    or greater than FC_WEIGHT_EXTRABLACK, returns -1. Otherwise
3850    returns a number in the range 1 to 1000.
3851
3852 Since
3853
3854    version 2.12.92
3855
3856 FcWeightFromOpenType
3857
3858 Name
3859
3860    FcWeightFromOpenType -- Convert from OpenType weight values to
3861    fontconfig ones
3862
3863 Synopsis
3864
3865 #include <fontconfig/fontconfig.h>
3866
3867    int FcWeightFromOpenType(intot_weight);
3868
3869 Description
3870
3871    FcWeightFromOpenType is like FcWeightFromOpenTypeDouble but
3872    with integer arguments. Use the other function instead.
3873
3874 Since
3875
3876    version 2.11.91
3877
3878 FcWeightToOpenType
3879
3880 Name
3881
3882    FcWeightToOpenType -- Convert from fontconfig weight values to
3883    OpenType ones
3884
3885 Synopsis
3886
3887 #include <fontconfig/fontconfig.h>
3888
3889    int FcWeightToOpenType(intot_weight);
3890
3891 Description
3892
3893    FcWeightToOpenType is like FcWeightToOpenTypeDouble but with
3894    integer arguments. Use the other function instead.
3895
3896 Since
3897
3898    version 2.11.91
3899      __________________________________________________________
3900
3901 FcBlanks
3902
3903    Table of Contents
3904    FcBlanksCreate -- Create an FcBlanks
3905    FcBlanksDestroy -- Destroy and FcBlanks
3906    FcBlanksAdd -- Add a character to an FcBlanks
3907    FcBlanksIsMember -- Query membership in an FcBlanks
3908
3909    An FcBlanks object holds a list of Unicode chars which are
3910    expected to be blank when drawn. When scanning new fonts, any
3911    glyphs which are empty and not in this list will be assumed to
3912    be broken and not placed in the FcCharSet associated with the
3913    font. This provides a significantly more accurate CharSet for
3914    applications.
3915
3916    FcBlanks is deprecated and should not be used in newly written
3917    code. It is still accepted by some functions for compatibility
3918    with older code but will be removed in the future.
3919
3920 FcBlanksCreate
3921
3922 Name
3923
3924    FcBlanksCreate -- Create an FcBlanks
3925
3926 Synopsis
3927
3928 #include <fontconfig/fontconfig.h>
3929
3930    FcBlanks * FcBlanksCreate(void);
3931
3932 Description
3933
3934    FcBlanks is deprecated. This function always returns NULL.
3935
3936 FcBlanksDestroy
3937
3938 Name
3939
3940    FcBlanksDestroy -- Destroy and FcBlanks
3941
3942 Synopsis
3943
3944 #include <fontconfig/fontconfig.h>
3945
3946    void FcBlanksDestroy(FcBlanks *b);
3947
3948 Description
3949
3950    FcBlanks is deprecated. This function does nothing.
3951
3952 FcBlanksAdd
3953
3954 Name
3955
3956    FcBlanksAdd -- Add a character to an FcBlanks
3957
3958 Synopsis
3959
3960 #include <fontconfig/fontconfig.h>
3961
3962    FcBool FcBlanksAdd(FcBlanks *b, FcChar32 ucs4);
3963
3964 Description
3965
3966    FcBlanks is deprecated. This function always returns FALSE.
3967
3968 FcBlanksIsMember
3969
3970 Name
3971
3972    FcBlanksIsMember -- Query membership in an FcBlanks
3973
3974 Synopsis
3975
3976 #include <fontconfig/fontconfig.h>
3977
3978    FcBool FcBlanksIsMember(FcBlanks *b, FcChar32 ucs4);
3979
3980 Description
3981
3982    FcBlanks is deprecated. This function always returns FALSE.
3983      __________________________________________________________
3984
3985 FcAtomic
3986
3987    Table of Contents
3988    FcAtomicCreate -- create an FcAtomic object
3989    FcAtomicLock -- lock a file
3990    FcAtomicNewFile -- return new temporary file name
3991    FcAtomicOrigFile -- return original file name
3992    FcAtomicReplaceOrig -- replace original with new
3993    FcAtomicDeleteNew -- delete new file
3994    FcAtomicUnlock -- unlock a file
3995    FcAtomicDestroy -- destroy an FcAtomic object
3996
3997    These functions provide a safe way to update configuration
3998    files, allowing ongoing reading of the old configuration file
3999    while locked for writing and ensuring that a consistent and
4000    complete version of the configuration file is always available.
4001
4002 FcAtomicCreate
4003
4004 Name
4005
4006    FcAtomicCreate -- create an FcAtomic object
4007
4008 Synopsis
4009
4010 #include <fontconfig/fontconfig.h>
4011
4012    FcAtomic * FcAtomicCreate(const FcChar8 *file);
4013
4014 Description
4015
4016    Creates a data structure containing data needed to control
4017    access to file. Writing is done to a separate file. Once that
4018    file is complete, the original configuration file is atomically
4019    replaced so that reading process always see a consistent and
4020    complete file without the need to lock for reading.
4021
4022 FcAtomicLock
4023
4024 Name
4025
4026    FcAtomicLock -- lock a file
4027
4028 Synopsis
4029
4030 #include <fontconfig/fontconfig.h>
4031
4032    FcBool FcAtomicLock(FcAtomic *atomic);
4033
4034 Description
4035
4036    Attempts to lock the file referenced by atomic. Returns FcFalse
4037    if the file is already locked, else returns FcTrue and leaves
4038    the file locked.
4039
4040 FcAtomicNewFile
4041
4042 Name
4043
4044    FcAtomicNewFile -- return new temporary file name
4045
4046 Synopsis
4047
4048 #include <fontconfig/fontconfig.h>
4049
4050    FcChar8 * FcAtomicNewFile(FcAtomic *atomic);
4051
4052 Description
4053
4054    Returns the filename for writing a new version of the file
4055    referenced by atomic.
4056
4057 FcAtomicOrigFile
4058
4059 Name
4060
4061    FcAtomicOrigFile -- return original file name
4062
4063 Synopsis
4064
4065 #include <fontconfig/fontconfig.h>
4066
4067    FcChar8 * FcAtomicOrigFile(FcAtomic *atomic);
4068
4069 Description
4070
4071    Returns the file referenced by atomic.
4072
4073 FcAtomicReplaceOrig
4074
4075 Name
4076
4077    FcAtomicReplaceOrig -- replace original with new
4078
4079 Synopsis
4080
4081 #include <fontconfig/fontconfig.h>
4082
4083    FcBool FcAtomicReplaceOrig(FcAtomic *atomic);
4084
4085 Description
4086
4087    Replaces the original file referenced by atomic with the new
4088    file. Returns FcFalse if the file cannot be replaced due to
4089    permission issues in the filesystem. Otherwise returns FcTrue.
4090
4091 FcAtomicDeleteNew
4092
4093 Name
4094
4095    FcAtomicDeleteNew -- delete new file
4096
4097 Synopsis
4098
4099 #include <fontconfig/fontconfig.h>
4100
4101    void FcAtomicDeleteNew(FcAtomic *atomic);
4102
4103 Description
4104
4105    Deletes the new file. Used in error recovery to back out
4106    changes.
4107
4108 FcAtomicUnlock
4109
4110 Name
4111
4112    FcAtomicUnlock -- unlock a file
4113
4114 Synopsis
4115
4116 #include <fontconfig/fontconfig.h>
4117
4118    void FcAtomicUnlock(FcAtomic *atomic);
4119
4120 Description
4121
4122    Unlocks the file.
4123
4124 FcAtomicDestroy
4125
4126 Name
4127
4128    FcAtomicDestroy -- destroy an FcAtomic object
4129
4130 Synopsis
4131
4132 #include <fontconfig/fontconfig.h>
4133
4134    void FcAtomicDestroy(FcAtomic *atomic);
4135
4136 Description
4137
4138    Destroys atomic.
4139      __________________________________________________________
4140
4141 File and Directory routines
4142
4143    Table of Contents
4144    FcFileScan -- scan a font file
4145    FcFileIsDir -- check whether a file is a directory
4146    FcDirScan -- scan a font directory without caching it
4147    FcDirSave -- DEPRECATED: formerly used to save a directory
4148           cache
4149
4150    FcDirCacheUnlink -- Remove all caches related to dir
4151    FcDirCacheValid -- check directory cache
4152    FcDirCacheLoad -- load a directory cache
4153    FcDirCacheRescan -- Re-scan a directory cache
4154    FcDirCacheRead -- read or construct a directory cache
4155    FcDirCacheLoadFile -- load a cache file
4156    FcDirCacheUnload -- unload a cache file
4157
4158    These routines work with font files and directories, including
4159    font directory cache files.
4160
4161 FcFileScan
4162
4163 Name
4164
4165    FcFileScan -- scan a font file
4166
4167 Synopsis
4168
4169 #include <fontconfig/fontconfig.h>
4170
4171    FcBool FcFileScan(FcFontSet *set, FcStrSet *dirs, FcFileCache
4172    *cache, FcBlanks *blanks, const FcChar8 *file, FcBool force);
4173
4174 Description
4175
4176    Scans a single file and adds all fonts found to set. If force
4177    is FcTrue, then the file is scanned even if associated
4178    information is found in cache. If file is a directory, it is
4179    added to dirs. Whether fonts are found depends on fontconfig
4180    policy as well as the current configuration. Internally,
4181    fontconfig will ignore BDF and PCF fonts which are not in
4182    Unicode (or the effectively equivalent ISO Latin-1) encoding as
4183    those are not usable by Unicode-based applications. The
4184    configuration can ignore fonts based on filename or contents of
4185    the font file itself. Returns FcFalse if any of the fonts
4186    cannot be added (due to allocation failure). Otherwise returns
4187    FcTrue.
4188
4189 FcFileIsDir
4190
4191 Name
4192
4193    FcFileIsDir -- check whether a file is a directory
4194
4195 Synopsis
4196
4197 #include <fontconfig/fontconfig.h>
4198
4199    FcBool FcFileIsDir(const FcChar8 *file);
4200
4201 Description
4202
4203    Returns FcTrue if file is a directory, otherwise returns
4204    FcFalse.
4205
4206 FcDirScan
4207
4208 Name
4209
4210    FcDirScan -- scan a font directory without caching it
4211
4212 Synopsis
4213
4214 #include <fontconfig/fontconfig.h>
4215
4216    FcBool FcDirScan(FcFontSet *set, FcStrSet *dirs, FcFileCache
4217    *cache, FcBlanks *blanks, const FcChar8 *dir, FcBool force);
4218
4219 Description
4220
4221    If cache is not zero or if force is FcFalse, this function
4222    currently returns FcFalse. Otherwise, it scans an entire
4223    directory and adds all fonts found to set. Any subdirectories
4224    found are added to dirs. Calling this function does not create
4225    any cache files. Use FcDirCacheRead() if caching is desired.
4226
4227 FcDirSave
4228
4229 Name
4230
4231    FcDirSave -- DEPRECATED: formerly used to save a directory
4232    cache
4233
4234 Synopsis
4235
4236 #include <fontconfig/fontconfig.h>
4237
4238    FcBool FcDirSave(FcFontSet *set, FcStrSet *dirs, const FcChar8
4239    *dir);
4240
4241 Description
4242
4243    This function now does nothing aside from returning FcFalse. It
4244    used to creates the per-directory cache file for dir and
4245    populates it with the fonts in set and subdirectories in dirs.
4246    All of this functionality is now automatically managed by
4247    FcDirCacheLoad and FcDirCacheRead.
4248
4249 FcDirCacheUnlink
4250
4251 Name
4252
4253    FcDirCacheUnlink -- Remove all caches related to dir
4254
4255 Synopsis
4256
4257 #include <fontconfig/fontconfig.h>
4258
4259    FcBool FcDirCacheUnlink(const FcChar8 *dir, FcConfig *config);
4260
4261 Description
4262
4263    Scans the cache directories in config, removing any instances
4264    of the cache file for dir. Returns FcFalse when some internal
4265    error occurs (out of memory, etc). Errors actually unlinking
4266    any files are ignored.
4267
4268 FcDirCacheValid
4269
4270 Name
4271
4272    FcDirCacheValid -- check directory cache
4273
4274 Synopsis
4275
4276 #include <fontconfig/fontconfig.h>
4277
4278    FcBool FcDirCacheValid(const FcChar8 *dir);
4279
4280 Description
4281
4282    Returns FcTrue if dir has an associated valid cache file, else
4283    returns FcFalse
4284
4285 FcDirCacheLoad
4286
4287 Name
4288
4289    FcDirCacheLoad -- load a directory cache
4290
4291 Synopsis
4292
4293 #include <fontconfig/fontconfig.h>
4294
4295    FcCache * FcDirCacheLoad(const FcChar8 *dir, FcConfig *config,
4296    FcChar8 **cache_file);
4297
4298 Description
4299
4300    Loads the cache related to dir. If no cache file exists,
4301    returns NULL. The name of the cache file is returned in
4302    cache_file, unless that is NULL. See also FcDirCacheRead.
4303
4304 FcDirCacheRescan
4305
4306 Name
4307
4308    FcDirCacheRescan -- Re-scan a directory cache
4309
4310 Synopsis
4311
4312 #include <fontconfig/fontconfig.h>
4313
4314    FcCache * FcDirCacheRescan(const FcChar8 *dir, FcConfig
4315    *config);
4316
4317 Description
4318
4319    Re-scan directories only at dir and update the cache. returns
4320    NULL if failed.
4321
4322 Since
4323
4324    version 2.11.1
4325
4326 FcDirCacheRead
4327
4328 Name
4329
4330    FcDirCacheRead -- read or construct a directory cache
4331
4332 Synopsis
4333
4334 #include <fontconfig/fontconfig.h>
4335
4336    FcCache * FcDirCacheRead(const FcChar8 *dir, FcBool force,
4337    FcConfig *config);
4338
4339 Description
4340
4341    This returns a cache for dir. If force is FcFalse, then an
4342    existing, valid cache file will be used. Otherwise, a new cache
4343    will be created by scanning the directory and that returned.
4344
4345 FcDirCacheLoadFile
4346
4347 Name
4348
4349    FcDirCacheLoadFile -- load a cache file
4350
4351 Synopsis
4352
4353 #include <fontconfig/fontconfig.h>
4354
4355    FcCache * FcDirCacheLoadFile(const FcChar8 *cache_file, struct
4356    stat *file_stat);
4357
4358 Description
4359
4360    This function loads a directory cache from cache_file. If
4361    file_stat is non-NULL, it will be filled with the results of
4362    stat(2) on the cache file.
4363
4364 FcDirCacheUnload
4365
4366 Name
4367
4368    FcDirCacheUnload -- unload a cache file
4369
4370 Synopsis
4371
4372 #include <fontconfig/fontconfig.h>
4373
4374    void FcDirCacheUnload(FcCache *cache);
4375
4376 Description
4377
4378    This function dereferences cache. When no other references to
4379    it remain, all memory associated with the cache will be freed.
4380      __________________________________________________________
4381
4382 FcCache routines
4383
4384    Table of Contents
4385    FcCacheDir -- Return directory of cache
4386    FcCacheCopySet -- Returns a copy of the fontset from cache
4387    FcCacheSubdir -- Return the i'th subdirectory.
4388    FcCacheNumSubdir -- Return the number of subdirectories in
4389           cache.
4390
4391    FcCacheNumFont -- Returns the number of fonts in cache.
4392    FcDirCacheClean -- Clean up a cache directory
4393    FcCacheCreateTagFile -- Create CACHEDIR.TAG at cache directory.
4394    FcDirCacheCreateUUID -- Create .uuid file at a directory
4395
4396    These routines work with font directory caches, accessing their
4397    contents in limited ways. It is not expected that normal
4398    applications will need to use these functions.
4399
4400 FcCacheDir
4401
4402 Name
4403
4404    FcCacheDir -- Return directory of cache
4405
4406 Synopsis
4407
4408 #include <fontconfig/fontconfig.h>
4409
4410    const FcChar8 * FcCacheDir(const FcCache *cache);
4411
4412 Description
4413
4414    This function returns the directory from which the cache was
4415    constructed.
4416
4417 FcCacheCopySet
4418
4419 Name
4420
4421    FcCacheCopySet -- Returns a copy of the fontset from cache
4422
4423 Synopsis
4424
4425 #include <fontconfig/fontconfig.h>
4426
4427    FcFontSet * FcCacheCopySet(const FcCache *cache);
4428
4429 Description
4430
4431    The returned fontset contains each of the font patterns from
4432    cache. This fontset may be modified, but the patterns from the
4433    cache are read-only.
4434
4435 FcCacheSubdir
4436
4437 Name
4438
4439    FcCacheSubdir -- Return the i'th subdirectory.
4440
4441 Synopsis
4442
4443 #include <fontconfig/fontconfig.h>
4444
4445    const FcChar8 * FcCacheSubdir(const FcCache *cache, inti);
4446
4447 Description
4448
4449    The set of subdirectories stored in a cache file are indexed by
4450    this function, i should range from 0 to n-1, where n is the
4451    return value from FcCacheNumSubdir.
4452
4453 FcCacheNumSubdir
4454
4455 Name
4456
4457    FcCacheNumSubdir -- Return the number of subdirectories in
4458    cache.
4459
4460 Synopsis
4461
4462 #include <fontconfig/fontconfig.h>
4463
4464    int FcCacheNumSubdir(const FcCache *cache);
4465
4466 Description
4467
4468    This returns the total number of subdirectories in the cache.
4469
4470 FcCacheNumFont
4471
4472 Name
4473
4474    FcCacheNumFont -- Returns the number of fonts in cache.
4475
4476 Synopsis
4477
4478 #include <fontconfig/fontconfig.h>
4479
4480    int FcCacheNumFont(const FcCache *cache);
4481
4482 Description
4483
4484    This returns the number of fonts which would be included in the
4485    return from FcCacheCopySet.
4486
4487 FcDirCacheClean
4488
4489 Name
4490
4491    FcDirCacheClean -- Clean up a cache directory
4492
4493 Synopsis
4494
4495 #include <fontconfig/fontconfig.h>
4496
4497    FcBool FcDirCacheClean(const FcChar8 *cache_dir,
4498    FcBoolverbose);
4499
4500 Description
4501
4502    This tries to clean up the cache directory of cache_dir. This
4503    returns FcTrue if the operation is successfully complete.
4504    otherwise FcFalse.
4505
4506 Since
4507
4508    version 2.9.91
4509
4510 FcCacheCreateTagFile
4511
4512 Name
4513
4514    FcCacheCreateTagFile -- Create CACHEDIR.TAG at cache directory.
4515
4516 Synopsis
4517
4518 #include <fontconfig/fontconfig.h>
4519
4520    void FcCacheCreateTagFile(const FcConfig *config);
4521
4522 Description
4523
4524    This tries to create CACHEDIR.TAG file at the cache directory
4525    registered to config.
4526
4527 Since
4528
4529    version 2.9.91
4530
4531 FcDirCacheCreateUUID
4532
4533 Name
4534
4535    FcDirCacheCreateUUID -- Create .uuid file at a directory
4536
4537 Synopsis
4538
4539 #include <fontconfig/fontconfig.h>
4540
4541    FcBool FcDirCacheCreateUUID(FcChar8 *dir, FcBoolforce,
4542    FcConfigconfig);
4543
4544 Description
4545
4546    This is to create .uuid file containing an UUID at a font
4547    directory of dir. The UUID will be used to identify the font
4548    directory and is used to determine the cache filename if
4549    available.
4550
4551 Since
4552
4553    version 2.12.92
4554      __________________________________________________________
4555
4556 FcStrSet and FcStrList
4557
4558    Table of Contents
4559    FcStrSetCreate -- create a string set
4560    FcStrSetMember -- check set for membership
4561    FcStrSetEqual -- check sets for equality
4562    FcStrSetAdd -- add to a string set
4563    FcStrSetAddFilename -- add a filename to a string set
4564    FcStrSetDel -- delete from a string set
4565    FcStrSetDestroy -- destroy a string set
4566    FcStrListCreate -- create a string iterator
4567    FcStrListFirst -- get first string in iteration
4568    FcStrListNext -- get next string in iteration
4569    FcStrListDone -- destroy a string iterator
4570
4571    A data structure for enumerating strings, used to list
4572    directories while scanning the configuration as directories are
4573    added while scanning.
4574
4575 FcStrSetCreate
4576
4577 Name
4578
4579    FcStrSetCreate -- create a string set
4580
4581 Synopsis
4582
4583 #include <fontconfig/fontconfig.h>
4584
4585    FcStrSet * FcStrSetCreate(void);
4586
4587 Description
4588
4589    Create an empty set.
4590
4591 FcStrSetMember
4592
4593 Name
4594
4595    FcStrSetMember -- check set for membership
4596
4597 Synopsis
4598
4599 #include <fontconfig/fontconfig.h>
4600
4601    FcBool FcStrSetMember(FcStrSet *set, const FcChar8 *s);
4602
4603 Description
4604
4605    Returns whether s is a member of set.
4606
4607 FcStrSetEqual
4608
4609 Name
4610
4611    FcStrSetEqual -- check sets for equality
4612
4613 Synopsis
4614
4615 #include <fontconfig/fontconfig.h>
4616
4617    FcBool FcStrSetEqual(FcStrSet *set_a, FcStrSet *set_b);
4618
4619 Description
4620
4621    Returns whether set_a contains precisely the same strings as
4622    set_b. Ordering of strings within the two sets is not
4623    considered.
4624
4625 FcStrSetAdd
4626
4627 Name
4628
4629    FcStrSetAdd -- add to a string set
4630
4631 Synopsis
4632
4633 #include <fontconfig/fontconfig.h>
4634
4635    FcBool FcStrSetAdd(FcStrSet *set, const FcChar8 *s);
4636
4637 Description
4638
4639    Adds a copy of s to set.
4640
4641 FcStrSetAddFilename
4642
4643 Name
4644
4645    FcStrSetAddFilename -- add a filename to a string set
4646
4647 Synopsis
4648
4649 #include <fontconfig/fontconfig.h>
4650
4651    FcBool FcStrSetAddFilename(FcStrSet *set, const FcChar8 *s);
4652
4653 Description
4654
4655    Adds a copy s to set, The copy is created with
4656    FcStrCopyFilename so that leading '~' values are replaced with
4657    the value of the HOME environment variable.
4658
4659 FcStrSetDel
4660
4661 Name
4662
4663    FcStrSetDel -- delete from a string set
4664
4665 Synopsis
4666
4667 #include <fontconfig/fontconfig.h>
4668
4669    FcBool FcStrSetDel(FcStrSet *set, const FcChar8 *s);
4670
4671 Description
4672
4673    Removes s from set, returning FcTrue if s was a member else
4674    FcFalse.
4675
4676 FcStrSetDestroy
4677
4678 Name
4679
4680    FcStrSetDestroy -- destroy a string set
4681
4682 Synopsis
4683
4684 #include <fontconfig/fontconfig.h>
4685
4686    void FcStrSetDestroy(FcStrSet *set);
4687
4688 Description
4689
4690    Destroys set.
4691
4692 FcStrListCreate
4693
4694 Name
4695
4696    FcStrListCreate -- create a string iterator
4697
4698 Synopsis
4699
4700 #include <fontconfig/fontconfig.h>
4701
4702    FcStrList * FcStrListCreate(FcStrSet *set);
4703
4704 Description
4705
4706    Creates an iterator to list the strings in set.
4707
4708 FcStrListFirst
4709
4710 Name
4711
4712    FcStrListFirst -- get first string in iteration
4713
4714 Synopsis
4715
4716 #include <fontconfig/fontconfig.h>
4717
4718    void FcStrListFirst(FcStrList *list);
4719
4720 Description
4721
4722    Returns the first string in list.
4723
4724 Since
4725
4726    version 2.11.0
4727
4728 FcStrListNext
4729
4730 Name
4731
4732    FcStrListNext -- get next string in iteration
4733
4734 Synopsis
4735
4736 #include <fontconfig/fontconfig.h>
4737
4738    FcChar8 * FcStrListNext(FcStrList *list);
4739
4740 Description
4741
4742    Returns the next string in list.
4743
4744 FcStrListDone
4745
4746 Name
4747
4748    FcStrListDone -- destroy a string iterator
4749
4750 Synopsis
4751
4752 #include <fontconfig/fontconfig.h>
4753
4754    void FcStrListDone(FcStrList *list);
4755
4756 Description
4757
4758    Destroys the enumerator list.
4759      __________________________________________________________
4760
4761 String utilities
4762
4763    Table of Contents
4764    FcUtf8ToUcs4 -- convert UTF-8 to UCS4
4765    FcUcs4ToUtf8 -- convert UCS4 to UTF-8
4766    FcUtf8Len -- count UTF-8 encoded chars
4767    FcUtf16ToUcs4 -- convert UTF-16 to UCS4
4768    FcUtf16Len -- count UTF-16 encoded chars
4769    FcIsLower -- check for lower case ASCII character
4770    FcIsUpper -- check for upper case ASCII character
4771    FcToLower -- convert upper case ASCII to lower case
4772    FcStrCopy -- duplicate a string
4773    FcStrDowncase -- create a lower case translation of a string
4774    FcStrCopyFilename -- create a complete path from a filename
4775    FcStrCmp -- compare UTF-8 strings
4776    FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring case
4777    FcStrStr -- locate UTF-8 substring
4778    FcStrStrIgnoreCase -- locate UTF-8 substring ignoring ASCII
4779           case
4780
4781    FcStrPlus -- concatenate two strings
4782    FcStrFree -- free a string
4783    FcStrDirname -- directory part of filename
4784    FcStrBasename -- last component of filename
4785
4786    Fontconfig manipulates many UTF-8 strings represented with the
4787    FcChar8 type. These functions are exposed to help applications
4788    deal with these UTF-8 strings in a locale-insensitive manner.
4789
4790 FcUtf8ToUcs4
4791
4792 Name
4793
4794    FcUtf8ToUcs4 -- convert UTF-8 to UCS4
4795
4796 Synopsis
4797
4798 #include <fontconfig/fontconfig.h>
4799
4800    int FcUtf8ToUcs4(FcChar8 *src, FcChar32 *dst, int len);
4801
4802 Description
4803
4804    Converts the next Unicode char from src into dst and returns
4805    the number of bytes containing the char. src must be at least
4806    len bytes long.
4807
4808 FcUcs4ToUtf8
4809
4810 Name
4811
4812    FcUcs4ToUtf8 -- convert UCS4 to UTF-8
4813
4814 Synopsis
4815
4816 #include <fontconfig/fontconfig.h>
4817
4818    int FcUcs4ToUtf8(FcChar32 src, FcChar8 dst[FC_UTF8_MAX_LEN]);
4819
4820 Description
4821
4822    Converts the Unicode char from src into dst and returns the
4823    number of bytes needed to encode the char.
4824
4825 FcUtf8Len
4826
4827 Name
4828
4829    FcUtf8Len -- count UTF-8 encoded chars
4830
4831 Synopsis
4832
4833 #include <fontconfig/fontconfig.h>
4834
4835    FcBool FcUtf8Len(FcChar8 *src, int len, int *nchar, int
4836    *wchar);
4837
4838 Description
4839
4840    Counts the number of Unicode chars in len bytes of src. Places
4841    that count in nchar. wchar contains 1, 2 or 4 depending on the
4842    number of bytes needed to hold the largest Unicode char
4843    counted. The return value indicates whether src is a
4844    well-formed UTF8 string.
4845
4846 FcUtf16ToUcs4
4847
4848 Name
4849
4850    FcUtf16ToUcs4 -- convert UTF-16 to UCS4
4851
4852 Synopsis
4853
4854 #include <fontconfig/fontconfig.h>
4855
4856    int FcUtf16ToUcs4(FcChar8 *src, FcEndian endian, FcChar32 *dst,
4857    int len);
4858
4859 Description
4860
4861    Converts the next Unicode char from src into dst and returns
4862    the number of bytes containing the char. src must be at least
4863    len bytes long. Bytes of src are combined into 16-bit units
4864    according to endian.
4865
4866 FcUtf16Len
4867
4868 Name
4869
4870    FcUtf16Len -- count UTF-16 encoded chars
4871
4872 Synopsis
4873
4874 #include <fontconfig/fontconfig.h>
4875
4876    FcBool FcUtf16Len(FcChar8 *src, FcEndian endian, int len, int
4877    *nchar, int *wchar);
4878
4879 Description
4880
4881    Counts the number of Unicode chars in len bytes of src. Bytes
4882    of src are combined into 16-bit units according to endian.
4883    Places that count in nchar. wchar contains 1, 2 or 4 depending
4884    on the number of bytes needed to hold the largest Unicode char
4885    counted. The return value indicates whether string is a
4886    well-formed UTF16 string.
4887
4888 FcIsLower
4889
4890 Name
4891
4892    FcIsLower -- check for lower case ASCII character
4893
4894 Synopsis
4895
4896 #include <fontconfig/fontconfig.h>
4897
4898    FcBool FcIsLower(FcChar8c);
4899
4900 Description
4901
4902    This macro checks whether c is an lower case ASCII letter.
4903
4904 FcIsUpper
4905
4906 Name
4907
4908    FcIsUpper -- check for upper case ASCII character
4909
4910 Synopsis
4911
4912 #include <fontconfig/fontconfig.h>
4913
4914    FcBool FcIsUpper(FcChar8c);
4915
4916 Description
4917
4918    This macro checks whether c is a upper case ASCII letter.
4919
4920 FcToLower
4921
4922 Name
4923
4924    FcToLower -- convert upper case ASCII to lower case
4925
4926 Synopsis
4927
4928 #include <fontconfig/fontconfig.h>
4929
4930    FcChar8 FcToLower(FcChar8c);
4931
4932 Description
4933
4934    This macro converts upper case ASCII c to the equivalent lower
4935    case letter.
4936
4937 FcStrCopy
4938
4939 Name
4940
4941    FcStrCopy -- duplicate a string
4942
4943 Synopsis
4944
4945 #include <fontconfig/fontconfig.h>
4946
4947    FcChar8 * FcStrCopy(const FcChar8 *s);
4948
4949 Description
4950
4951    Allocates memory, copies s and returns the resulting buffer.
4952    Yes, this is strdup, but that function isn't available on every
4953    platform.
4954
4955 FcStrDowncase
4956
4957 Name
4958
4959    FcStrDowncase -- create a lower case translation of a string
4960
4961 Synopsis
4962
4963 #include <fontconfig/fontconfig.h>
4964
4965    FcChar8 * FcStrDowncase(const FcChar8 *s);
4966
4967 Description
4968
4969    Allocates memory, copies s, converting upper case letters to
4970    lower case and returns the allocated buffer.
4971
4972 FcStrCopyFilename
4973
4974 Name
4975
4976    FcStrCopyFilename -- create a complete path from a filename
4977
4978 Synopsis
4979
4980 #include <fontconfig/fontconfig.h>
4981
4982    FcChar8 * FcStrCopyFilename(const FcChar8 *s);
4983
4984 Description
4985
4986    FcStrCopyFilename constructs an absolute pathname from s. It
4987    converts any leading '~' characters in to the value of the HOME
4988    environment variable, and any relative paths are converted to
4989    absolute paths using the current working directory. Sequences
4990    of '/' characters are converted to a single '/', and names
4991    containing the current directory '.' or parent directory '..'
4992    are correctly reconstructed. Returns NULL if '~' is the leading
4993    character and HOME is unset or disabled (see
4994    FcConfigEnableHome).
4995
4996 FcStrCmp
4997
4998 Name
4999
5000    FcStrCmp -- compare UTF-8 strings
5001
5002 Synopsis
5003
5004 #include <fontconfig/fontconfig.h>
5005
5006    int FcStrCmp(const FcChar8 *s1, const FcChar8 *s2);
5007
5008 Description
5009
5010    Returns the usual <0, 0, >0 result of comparing s1 and s2.
5011
5012 FcStrCmpIgnoreCase
5013
5014 Name
5015
5016    FcStrCmpIgnoreCase -- compare UTF-8 strings ignoring case
5017
5018 Synopsis
5019
5020 #include <fontconfig/fontconfig.h>
5021
5022    int FcStrCmpIgnoreCase(const FcChar8 *s1, const FcChar8 *s2);
5023
5024 Description
5025
5026    Returns the usual <0, 0, >0 result of comparing s1 and s2. This
5027    test is case-insensitive for all proper UTF-8 encoded strings.
5028
5029 FcStrStr
5030
5031 Name
5032
5033    FcStrStr -- locate UTF-8 substring
5034
5035 Synopsis
5036
5037 #include <fontconfig/fontconfig.h>
5038
5039    FcChar8 * FcStrStr(const FcChar8 *s1, const FcChar8 *s2);
5040
5041 Description
5042
5043    Returns the location of s2 in s1. Returns NULL if s2 is not
5044    present in s1. This test will operate properly with UTF8
5045    encoded strings.
5046
5047 FcStrStrIgnoreCase
5048
5049 Name
5050
5051    FcStrStrIgnoreCase -- locate UTF-8 substring ignoring ASCII
5052    case
5053
5054 Synopsis
5055
5056 #include <fontconfig/fontconfig.h>
5057
5058    FcChar8 * FcStrStrIgnoreCase(const FcChar8 *s1, const FcChar8
5059    *s2);
5060
5061 Description
5062
5063    Returns the location of s2 in s1, ignoring case. Returns NULL
5064    if s2 is not present in s1. This test is case-insensitive for
5065    all proper UTF-8 encoded strings.
5066
5067 FcStrPlus
5068
5069 Name
5070
5071    FcStrPlus -- concatenate two strings
5072
5073 Synopsis
5074
5075 #include <fontconfig/fontconfig.h>
5076
5077    FcChar8 * FcStrPlus(const FcChar8 *s1, const FcChar8 *s2);
5078
5079 Description
5080
5081    This function allocates new storage and places the
5082    concatenation of s1 and s2 there, returning the new string.
5083
5084 FcStrFree
5085
5086 Name
5087
5088    FcStrFree -- free a string
5089
5090 Synopsis
5091
5092 #include <fontconfig/fontconfig.h>
5093
5094    void FcStrFree(FcChar8 *s);
5095
5096 Description
5097
5098    This is just a wrapper around free(3) which helps track memory
5099    usage of strings within the fontconfig library.
5100
5101 FcStrDirname
5102
5103 Name
5104
5105    FcStrDirname -- directory part of filename
5106
5107 Synopsis
5108
5109 #include <fontconfig/fontconfig.h>
5110
5111    FcChar8 * FcStrDirname(const FcChar8 *file);
5112
5113 Description
5114
5115    Returns the directory containing file. This is returned in
5116    newly allocated storage which should be freed when no longer
5117    needed.
5118
5119 FcStrBasename
5120
5121 Name
5122
5123    FcStrBasename -- last component of filename
5124
5125 Synopsis
5126
5127 #include <fontconfig/fontconfig.h>
5128
5129    FcChar8 * FcStrBasename(const FcChar8 *file);
5130
5131 Description
5132
5133    Returns the filename of file stripped of any leading directory
5134    names. This is returned in newly allocated storage which should
5135    be freed when no longer needed.