fcconfig.fncs revision ae02b298
1/* 2 * fontconfig/doc/fcconfig.fncs 3 * 4 * Copyright © 2003 Keith Packard 5 * 6 * Permission to use, copy, modify, distribute, and sell this software and its 7 * documentation for any purpose is hereby granted without fee, provided that 8 * the above copyright notice appear in all copies and that both that 9 * copyright notice and this permission notice appear in supporting 10 * documentation, and that the name of the author(s) not be used in 11 * advertising or 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 purpose. It 14 * is provided "as is" without express or implied warranty. 15 * 16 * THE AUTHOR(S) DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 17 * INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO 18 * EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY SPECIAL, INDIRECT OR 19 * CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, 20 * DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER 21 * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 22 * PERFORMANCE OF THIS SOFTWARE. 23 */ 24@RET@ FcConfig * 25@FUNC@ FcConfigCreate 26@TYPE1@ void 27@PURPOSE@ Create a configuration 28@DESC@ 29Creates an empty configuration. 30@@ 31 32@RET@ FcConfig * 33@FUNC@ FcConfigReference 34@TYPE1@ FcConfig * @ARG1@ config 35@PURPOSE@ Increment config reference count 36@DESC@ 37Add another reference to <parameter>config</parameter>. Configs are freed only 38when the reference count reaches zero. 39If <parameter>config</parameter> is NULL, the current configuration is used. 40In that case this function will be similar to FcConfigGetCurrent() except that 41it increments the reference count before returning and the user is responsible 42for destroying the configuration when not needed anymore. 43@@ 44 45@RET@ void 46@FUNC@ FcConfigDestroy 47@TYPE1@ FcConfig * @ARG1@ config 48@PURPOSE@ Destroy a configuration 49@DESC@ 50Decrements the config reference count. If all references are gone, destroys 51the configuration and any data associated with it. 52Note that calling this function with the return from FcConfigGetCurrent will 53cause a new configuration to be created for use as current configuration. 54@@ 55 56@RET@ FcBool 57@FUNC@ FcConfigSetCurrent 58@TYPE1@ FcConfig * @ARG1@ config 59@PURPOSE@ Set configuration as default 60@DESC@ 61Sets the current default configuration to <parameter>config</parameter>. Implicitly calls 62FcConfigBuildFonts if necessary, and FcConfigReference() to inrease the reference count 63in <parameter>config</parameter> since 2.12.0, returning FcFalse if that call fails. 64@@ 65 66@RET@ FcConfig * 67@FUNC@ FcConfigGetCurrent 68@TYPE1@ void 69@PURPOSE@ Return current configuration 70@DESC@ 71Returns the current default configuration. 72@@ 73 74@RET@ FcBool 75@FUNC@ FcConfigUptoDate 76@TYPE1@ FcConfig * @ARG1@ config 77@PURPOSE@ Check timestamps on config files 78@DESC@ 79Checks all of the files related to <parameter>config</parameter> and returns 80whether any of them has been modified since the configuration was created. 81If <parameter>config</parameter> is NULL, the current configuration is used. 82@@ 83 84@RET@ FcChar8 * 85@FUNC@ FcConfigHome 86@TYPE1@ void 87@PURPOSE@ return the current home directory. 88@DESC@ 89Return the current user's home directory, if it is available, and if using it 90is enabled, and NULL otherwise. 91See also <function>FcConfigEnableHome</function>). 92@@ 93 94@RET@ FcBool 95@FUNC@ FcConfigEnableHome 96@TYPE1@ FcBool% @ARG1@ enable 97@PURPOSE@ controls use of the home directory. 98@DESC@ 99If <parameter>enable</parameter> is FcTrue, then Fontconfig will use various 100files which are specified relative to the user's home directory (using the ~ 101notation in the configuration). When <parameter>enable</parameter> is 102FcFalse, then all use of the home directory in these contexts will be 103disabled. The previous setting of the value is returned. 104@@ 105 106@RET@ FcBool 107@FUNC@ FcConfigBuildFonts 108@TYPE1@ FcConfig * @ARG1@ config 109@PURPOSE@ Build font database 110@DESC@ 111Builds the set of available fonts for the given configuration. Note that 112any changes to the configuration after this call (through 113<function>FcConfigParseAndLoad</function> or 114<function>FcConfigParseAndLoadFromMemory</function>) have indeterminate 115effects. (On the other hand, application fonts can still be modified 116through <function>FcConfigAppFontAddFile</function>, 117<function>FcConfigAppFontAddDir</function> and 118<function>FcConfigAppFontClear</function>). Returns FcFalse if this operation 119runs out of memory. If <parameter>config</parameter> is NULL, the current 120configuration is used. 121@@ 122 123@RET@ FcStrList * 124@FUNC@ FcConfigGetConfigDirs 125@TYPE1@ FcConfig * @ARG1@ config 126@PURPOSE@ Get config directories 127@DESC@ 128Returns the list of font directories specified in the configuration files 129for <parameter>config</parameter>. Does not include any subdirectories. 130If <parameter>config</parameter> is NULL, the current configuration is used. 131@@ 132 133@RET@ FcStrList * 134@FUNC@ FcConfigGetFontDirs 135@TYPE1@ FcConfig * @ARG1@ config 136@PURPOSE@ Get font directories 137@DESC@ 138Returns the list of font directories in <parameter>config</parameter>. This includes the 139configured font directories along with any directories below those in the 140filesystem. 141If <parameter>config</parameter> is NULL, the current configuration is used. 142@@ 143 144@RET@ FcStrList * 145@FUNC@ FcConfigGetConfigFiles 146@TYPE1@ FcConfig * @ARG1@ config 147@PURPOSE@ Get config files 148@DESC@ 149Returns the list of known configuration files used to generate <parameter>config</parameter>. 150If <parameter>config</parameter> is NULL, the current configuration is used. 151@@ 152 153@RET@ FcChar8 * 154@FUNC@ FcConfigGetCache 155@TYPE1@ FcConfig * @ARG1@ config 156@PURPOSE@ DEPRECATED used to return per-user cache filename 157@DESC@ 158With fontconfig no longer using per-user cache files, this function now 159simply returns NULL to indicate that no per-user file exists. 160@@ 161 162@RET@ FcStrList * 163@FUNC@ FcConfigGetCacheDirs 164@TYPE1@ const FcConfig * @ARG1@ config 165@PURPOSE@ return the list of directories searched for cache files 166@DESC@ 167<function>FcConfigGetCacheDirs</function> returns a string list containing 168all of the directories that fontconfig will search when attempting to load a 169cache file for a font directory. 170If <parameter>config</parameter> is NULL, the current configuration is used. 171@@ 172 173@RET@ FcFontSet * 174@FUNC@ FcConfigGetFonts 175@TYPE1@ FcConfig * @ARG1@ config 176@TYPE2@ FcSetName% @ARG2@ set 177@PURPOSE@ Get config font set 178@DESC@ 179Returns one of the two sets of fonts from the configuration as specified 180by <parameter>set</parameter>. This font set is owned by the library and must 181not be modified or freed. 182If <parameter>config</parameter> is NULL, the current configuration is used. 183 </para><para> 184This function isn't MT-safe. <function>FcConfigReference</function> must be called 185before using this and then <function>FcConfigDestroy</function> when 186the return value is no longer referenced. 187@@ 188 189@RET@ FcBlanks * 190@FUNC@ FcConfigGetBlanks 191@TYPE1@ FcConfig * @ARG1@ config 192@PURPOSE@ Get config blanks 193@DESC@ 194FcBlanks is deprecated. 195This function always returns NULL. 196@@ 197 198@RET@ int 199@FUNC@ FcConfigGetRescanInterval 200@TYPE1@ FcConfig * @ARG1@ config 201@PURPOSE@ Get config rescan interval 202@DESC@ 203Returns the interval between automatic checks of the configuration (in 204seconds) specified in <parameter>config</parameter>. The configuration is checked during 205a call to FcFontList when this interval has passed since the last check. 206An interval setting of zero disables automatic checks. 207If <parameter>config</parameter> is NULL, the current configuration is used. 208@@ 209 210@RET@ FcBool 211@FUNC@ FcConfigSetRescanInterval 212@TYPE1@ FcConfig * @ARG1@ config 213@TYPE2@ int% @ARG2@ rescanInterval 214@PURPOSE@ Set config rescan interval 215@DESC@ 216Sets the rescan interval. Returns FcFalse if the interval cannot be set (due 217to allocation failure). Otherwise returns FcTrue. 218An interval setting of zero disables automatic checks. 219If <parameter>config</parameter> is NULL, the current configuration is used. 220@@ 221 222@RET@ FcBool 223@FUNC@ FcConfigAppFontAddFile 224@TYPE1@ FcConfig * @ARG1@ config 225@TYPE2@ const FcChar8 * @ARG2@ file 226@PURPOSE@ Add font file to font database 227@DESC@ 228Adds an application-specific font to the configuration. Returns FcFalse 229if the fonts cannot be added (due to allocation failure or no fonts found). 230Otherwise returns FcTrue. If <parameter>config</parameter> is NULL, 231the current configuration is used. 232@@ 233 234@RET@ FcBool 235@FUNC@ FcConfigAppFontAddDir 236@TYPE1@ FcConfig * @ARG1@ config 237@TYPE2@ const FcChar8 * @ARG2@ dir 238@PURPOSE@ Add fonts from directory to font database 239@DESC@ 240Scans the specified directory for fonts, adding each one found to the 241application-specific set of fonts. Returns FcFalse 242if the fonts cannot be added (due to allocation failure). 243Otherwise returns FcTrue. If <parameter>config</parameter> is NULL, 244the current configuration is used. 245@@ 246 247@RET@ void 248@FUNC@ FcConfigAppFontClear 249@TYPE1@ FcConfig * @ARG1@ config 250@PURPOSE@ Remove all app fonts from font database 251@DESC@ 252Clears the set of application-specific fonts. 253If <parameter>config</parameter> is NULL, the current configuration is used. 254@@ 255 256@RET@ FcBool 257@FUNC@ FcConfigSubstituteWithPat 258@TYPE1@ FcConfig * @ARG1@ config 259@TYPE2@ FcPattern * @ARG2@ p 260@TYPE3@ FcPattern * @ARG3@ p_pat 261@TYPE4@ FcMatchKind% @ARG4@ kind 262@PURPOSE@ Execute substitutions 263@DESC@ 264Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is 265FcMatchPattern, then those tagged as pattern operations are applied, else 266if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and 267p_pat is used for <test> elements with target=pattern. Returns FcFalse 268if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue. 269If <parameter>config</parameter> is NULL, the current configuration is used. 270@@ 271 272@RET@ FcBool 273@FUNC@ FcConfigSubstitute 274@TYPE1@ FcConfig * @ARG1@ config 275@TYPE2@ FcPattern * @ARG2@ p 276@TYPE3@ FcMatchKind% @ARG3@ kind 277@PURPOSE@ Execute substitutions 278@DESC@ 279Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns FcFalse 280if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue. 281If <parameter>config</parameter> is NULL, the current configuration is used. 282@@ 283 284@RET@ FcPattern * 285@FUNC@ FcFontMatch 286@TYPE1@ FcConfig * @ARG1@ config 287@TYPE2@ FcPattern * @ARG2@ p 288@TYPE3@ FcResult * @ARG3@ result 289@PURPOSE@ Return best font 290@DESC@ 291Finds the font in <parameter>sets</parameter> most closely matching 292<parameter>pattern</parameter> and returns the result of 293<function>FcFontRenderPrepare</function> for that font and the provided 294pattern. This function should be called only after 295<function>FcConfigSubstitute</function> and 296<function>FcDefaultSubstitute</function> have been called for 297<parameter>p</parameter>; otherwise the results will not be correct. 298If <parameter>config</parameter> is NULL, the current configuration is used. 299@@ 300 301@RET@ FcFontSet * 302@FUNC@ FcFontSort 303@TYPE1@ FcConfig * @ARG1@ config 304@TYPE2@ FcPattern * @ARG2@ p 305@TYPE3@ FcBool% @ARG3@ trim 306@TYPE4@ FcCharSet ** @ARG4@ csp 307@TYPE5@ FcResult * @ARG5@ result 308@PURPOSE@ Return list of matching fonts 309@DESC@ 310Returns the list of fonts sorted by closeness to <parameter>p</parameter>. If <parameter>trim</parameter> is FcTrue, 311elements in the list which don't include Unicode coverage not provided by 312earlier elements in the list are elided. The union of Unicode coverage of 313all of the fonts is returned in <parameter>csp</parameter>, if <parameter>csp</parameter> is not NULL. This function 314should be called only after FcConfigSubstitute and FcDefaultSubstitute have 315been called for <parameter>p</parameter>; otherwise the results will not be correct. 316 </para><para> 317The returned FcFontSet references FcPattern structures which may be shared 318by the return value from multiple FcFontSort calls, applications must not 319modify these patterns. Instead, they should be passed, along with <parameter>p</parameter> to 320<function>FcFontRenderPrepare</function> which combines them into a complete pattern. 321 </para><para> 322The FcFontSet returned by FcFontSort is destroyed by calling FcFontSetDestroy. 323If <parameter>config</parameter> is NULL, the current configuration is used. 324@@ 325 326@RET@ FcPattern * 327@FUNC@ FcFontRenderPrepare 328@TYPE1@ FcConfig * @ARG1@ config 329@TYPE2@ FcPattern * @ARG2@ pat 330@TYPE3@ FcPattern * @ARG3@ font 331@PURPOSE@ Prepare pattern for loading font file 332@DESC@ 333Creates a new pattern consisting of elements of <parameter>font</parameter> not appearing 334in <parameter>pat</parameter>, elements of <parameter>pat</parameter> not appearing in <parameter>font</parameter> and the best matching 335value from <parameter>pat</parameter> for elements appearing in both. The result is passed to 336FcConfigSubstituteWithPat with <parameter>kind</parameter> FcMatchFont and then returned. 337@@ 338 339@RET@ FcFontSet * 340@FUNC@ FcFontList 341@TYPE1@ FcConfig * @ARG1@ config 342@TYPE2@ FcPattern * @ARG2@ p 343@TYPE3@ FcObjectSet * @ARG3@ os 344@PURPOSE@ List fonts 345@DESC@ 346Selects fonts matching <parameter>p</parameter>, creates patterns from those fonts containing 347only the objects in <parameter>os</parameter> and returns the set of unique such patterns. 348If <parameter>config</parameter> is NULL, the default configuration is checked 349to be up to date, and used. 350@@ 351 352@RET@ FcChar8 * 353@FUNC@ FcConfigFilename 354@TYPE1@ const FcChar8 * @ARG1@ name 355@PURPOSE@ Find a config file 356@DESC@ 357This function is deprecated and is replaced by <function>FcConfigGetFilename</function>. 358@@ 359 360@RET@ FcChar8 * 361@FUNC@ FcConfigGetFilename 362@TYPE1@ FcConfig * @ARG1@ config 363@TYPE2@ const FcChar8 * @ARG2@ name 364@PURPOSE@ Find a config file 365@DESC@ 366Given the specified external entity name, return the associated filename. 367This provides applications a way to convert various configuration file 368references into filename form. 369 </para><para> 370A null or empty <parameter>name</parameter> indicates that the default configuration file should 371be used; which file this references can be overridden with the 372FONTCONFIG_FILE environment variable. Next, if the name starts with <parameter>~</parameter>, it 373refers to a file in the current users home directory. Otherwise if the name 374doesn't start with '/', it refers to a file in the default configuration 375directory; the built-in default directory can be overridden with the 376FONTCONFIG_PATH environment variable. 377 </para><para> 378The result of this function is affected by the FONTCONFIG_SYSROOT environment variable or equivalent functionality. 379@@ 380 381@RET@ FcBool 382@FUNC@ FcConfigParseAndLoad 383@TYPE1@ FcConfig * @ARG1@ config 384@TYPE2@ const FcChar8 * @ARG2@ file 385@TYPE3@ FcBool% @ARG3@ complain 386@PURPOSE@ load a configuration file 387@DESC@ 388Walks the configuration in 'file' and constructs the internal representation 389in 'config'. Any include files referenced from within 'file' will be loaded 390and parsed. If 'complain' is FcFalse, no warning will be displayed if 391'file' does not exist. Error and warning messages will be output to stderr. 392Returns FcFalse if some error occurred while loading the file, either a 393parse error, semantic error or allocation failure. Otherwise returns FcTrue. 394 395After all configuration files / strings have been loaded, with 396<function>FcConfigParseAndLoad</function> and/or 397<function>FcConfigParseAndLoadFromMemory</function>, call 398<function>FcConfigBuildFonts</function> to build the font 399database. 400@@ 401 402@RET@ FcBool 403@FUNC@ FcConfigParseAndLoadFromMemory 404@TYPE1@ FcConfig * @ARG1@ config 405@TYPE2@ const FcChar8 * @ARG2@ buffer 406@TYPE3@ FcBool% @ARG3@ complain 407@PURPOSE@ load a configuration from memory 408@DESC@ 409Walks the configuration in 'memory' and constructs the internal representation 410in 'config'. Any includes files referenced from within 'memory' will be loaded 411and dparsed. If 'complain' is FcFalse, no warning will be displayed if 412'file' does not exist. Error and warning messages will be output to stderr. 413Returns FcFalse if fsome error occurred while loading the file, either a 414parse error, semantic error or allocation failure. Otherwise returns FcTrue. 415 416After all configuration files / strings have been loaded, with 417<function>FcConfigParseAndLoad</function> and/or 418<function>FcConfigParseAndLoadFromMemory</function>, call 419<function>FcConfigBuildFonts</function> to build the font 420database. 421@SINCE@ 2.12.5 422@@ 423 424@RET@ const FcChar8 * 425@FUNC@ FcConfigGetSysRoot 426@TYPE1@ const FcConfig * @ARG1@ config 427@PURPOSE@ Obtain the system root directory 428@DESC@ 429Obtains the system root directory in 'config' if available. All files 430(including file properties in patterns) obtained from this 'config' are 431relative to this system root directory. 432 </para><para> 433This function isn't MT-safe. <function>FcConfigReference</function> must be called 434before using this and then <function>FcConfigDestroy</function> when 435the return value is no longer referenced. 436@SINCE@ 2.10.92 437@@ 438 439@RET@ void 440@FUNC@ FcConfigSetSysRoot 441@TYPE1@ FcConfig * @ARG1@ config 442@TYPE2@ const FcChar8 * @ARG2@ sysroot 443@PURPOSE@ Set the system root directory 444@DESC@ 445Set 'sysroot' as the system root directory. All file paths used or created with 446this 'config' (including file properties in patterns) will be considered or 447made relative to this 'sysroot'. This allows a host to generate caches for 448targets at build time. This also allows a cache to be re-targeted to a 449different base directory if 'FcConfigGetSysRoot' is used to resolve file paths. 450When setting this on the current config this causes changing current config 451(calls FcConfigSetCurrent()). 452@SINCE@ 2.10.92 453@@ 454 455@RET@ void 456@FUNC@ FcConfigFileInfoIterInit 457@TYPE1@ FcConfig * @ARG1@ config 458@TYPE2@ FcConfigFileInfoIter * @ARG2@ iter 459@PURPOSE@ Initialize the iterator 460@DESC@ 461Initialize 'iter' with the first iterator in the config file information list. 462 </para><para> 463The config file information list is stored in numerical order for filenames 464i.e. how fontconfig actually read them. 465 </para><para> 466This function isn't MT-safe. <function>FcConfigReference</function> must be called 467before using this and then <function>FcConfigDestroy</function> when the relevant 468values are no longer referenced. 469@SINCE@ 2.12.91 470@@ 471 472@RET@ FcBool 473@FUNC@ FcConfigFileInfoIterNext 474@TYPE1@ FcConfig * @ARG1@ config 475@TYPE2@ FcConfigFileInfoIter * @ARG2@ iter 476@PURPOSE@ Set the iterator to point to the next list 477@DESC@ 478Set 'iter' to point to the next node in the config file information list. 479If there is no next node, FcFalse is returned. 480 </para><para> 481This function isn't MT-safe. <function>FcConfigReference</function> must be called 482before using <function>FcConfigFileInfoIterInit</function> and then 483<function>FcConfigDestroy</function> when the relevant values are no longer referenced. 484@SINCE@ 2.12.91 485@@ 486 487@RET@ FcBool 488@FUNC@ FcConfigFileInfoIterGet 489@TYPE1@ FcConfig * @ARG1@ config 490@TYPE2@ FcConfigFileInfoIter * @ARG2@ iter 491@TYPE3@ FcChar8 ** @ARG3@ name 492@TYPE4@ FcChar8 ** @ARG4@ description 493@TYPE5@ FcBool * @ARG5@ enabled 494@PURPOSE@ Obtain the configuration file information 495@DESC@ 496Obtain the filename, the description and the flag whether it is enabled or not 497for 'iter' where points to current configuration file information. 498If the iterator is invalid, FcFalse is returned. 499 </para><para> 500This function isn't MT-safe. <function>FcConfigReference</function> must be called 501before using <function>FcConfigFileInfoIterInit</function> and then 502<function>FcConfigDestroy</function> when the relevant values are no longer referenced. 503@SINCE@ 2.12.91 504@@ 505