fcconfig.fncs revision a4e54154
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 have indeterminate effects. 113Returns FcFalse if this operation runs out of memory. 114If <parameter>config</parameter> is NULL, the current configuration is used. 115@@ 116 117@RET@ FcStrList * 118@FUNC@ FcConfigGetConfigDirs 119@TYPE1@ FcConfig * @ARG1@ config 120@PURPOSE@ Get config directories 121@DESC@ 122Returns the list of font directories specified in the configuration files 123for <parameter>config</parameter>. Does not include any subdirectories. 124If <parameter>config</parameter> is NULL, the current configuration is used. 125@@ 126 127@RET@ FcStrList * 128@FUNC@ FcConfigGetFontDirs 129@TYPE1@ FcConfig * @ARG1@ config 130@PURPOSE@ Get font directories 131@DESC@ 132Returns the list of font directories in <parameter>config</parameter>. This includes the 133configured font directories along with any directories below those in the 134filesystem. 135If <parameter>config</parameter> is NULL, the current configuration is used. 136@@ 137 138@RET@ FcStrList * 139@FUNC@ FcConfigGetConfigFiles 140@TYPE1@ FcConfig * @ARG1@ config 141@PURPOSE@ Get config files 142@DESC@ 143Returns the list of known configuration files used to generate <parameter>config</parameter>. 144If <parameter>config</parameter> is NULL, the current configuration is used. 145@@ 146 147@RET@ FcChar8 * 148@FUNC@ FcConfigGetCache 149@TYPE1@ FcConfig * @ARG1@ config 150@PURPOSE@ DEPRECATED used to return per-user cache filename 151@DESC@ 152With fontconfig no longer using per-user cache files, this function now 153simply returns NULL to indicate that no per-user file exists. 154@@ 155 156@RET@ FcStrList * 157@FUNC@ FcConfigGetCacheDirs 158@TYPE1@ const FcConfig * @ARG1@ config 159@PURPOSE@ return the list of directories searched for cache files 160@DESC@ 161<function>FcConfigGetCacheDirs</function> returns a string list containing 162all of the directories that fontconfig will search when attempting to load a 163cache file for a font directory. 164If <parameter>config</parameter> is NULL, the current configuration is used. 165@@ 166 167@RET@ FcFontSet * 168@FUNC@ FcConfigGetFonts 169@TYPE1@ FcConfig * @ARG1@ config 170@TYPE2@ FcSetName% @ARG2@ set 171@PURPOSE@ Get config font set 172@DESC@ 173Returns one of the two sets of fonts from the configuration as specified 174by <parameter>set</parameter>. This font set is owned by the library and must 175not be modified or freed. 176If <parameter>config</parameter> is NULL, the current configuration is used. 177 </para><para> 178This function isn't MT-safe. <function>FcConfigReference</function> must be called 179before using this and then <function>FcConfigDestroy</function> when 180the return value is no longer referenced. 181@@ 182 183@RET@ FcBlanks * 184@FUNC@ FcConfigGetBlanks 185@TYPE1@ FcConfig * @ARG1@ config 186@PURPOSE@ Get config blanks 187@DESC@ 188FcBlanks is deprecated. 189This function always returns NULL. 190@@ 191 192@RET@ int 193@FUNC@ FcConfigGetRescanInterval 194@TYPE1@ FcConfig * @ARG1@ config 195@PURPOSE@ Get config rescan interval 196@DESC@ 197Returns the interval between automatic checks of the configuration (in 198seconds) specified in <parameter>config</parameter>. The configuration is checked during 199a call to FcFontList when this interval has passed since the last check. 200An interval setting of zero disables automatic checks. 201If <parameter>config</parameter> is NULL, the current configuration is used. 202@@ 203 204@RET@ FcBool 205@FUNC@ FcConfigSetRescanInterval 206@TYPE1@ FcConfig * @ARG1@ config 207@TYPE2@ int% @ARG2@ rescanInterval 208@PURPOSE@ Set config rescan interval 209@DESC@ 210Sets the rescan interval. Returns FcFalse if the interval cannot be set (due 211to allocation failure). Otherwise returns FcTrue. 212An interval setting of zero disables automatic checks. 213If <parameter>config</parameter> is NULL, the current configuration is used. 214@@ 215 216@RET@ FcBool 217@FUNC@ FcConfigAppFontAddFile 218@TYPE1@ FcConfig * @ARG1@ config 219@TYPE2@ const FcChar8 * @ARG2@ file 220@PURPOSE@ Add font file to font database 221@DESC@ 222Adds an application-specific font to the configuration. Returns FcFalse 223if the fonts cannot be added (due to allocation failure or no fonts found). 224Otherwise returns FcTrue. If <parameter>config</parameter> is NULL, 225the current configuration is used. 226@@ 227 228@RET@ FcBool 229@FUNC@ FcConfigAppFontAddDir 230@TYPE1@ FcConfig * @ARG1@ config 231@TYPE2@ const FcChar8 * @ARG2@ dir 232@PURPOSE@ Add fonts from directory to font database 233@DESC@ 234Scans the specified directory for fonts, adding each one found to the 235application-specific set of fonts. Returns FcFalse 236if the fonts cannot be added (due to allocation failure). 237Otherwise returns FcTrue. If <parameter>config</parameter> is NULL, 238the current configuration is used. 239@@ 240 241@RET@ void 242@FUNC@ FcConfigAppFontClear 243@TYPE1@ FcConfig * @ARG1@ config 244@PURPOSE@ Remove all app fonts from font database 245@DESC@ 246Clears the set of application-specific fonts. 247If <parameter>config</parameter> is NULL, the current configuration is used. 248@@ 249 250@RET@ FcBool 251@FUNC@ FcConfigSubstituteWithPat 252@TYPE1@ FcConfig * @ARG1@ config 253@TYPE2@ FcPattern * @ARG2@ p 254@TYPE3@ FcPattern * @ARG3@ p_pat 255@TYPE4@ FcMatchKind% @ARG4@ kind 256@PURPOSE@ Execute substitutions 257@DESC@ 258Performs the sequence of pattern modification operations, if <parameter>kind</parameter> is 259FcMatchPattern, then those tagged as pattern operations are applied, else 260if <parameter>kind</parameter> is FcMatchFont, those tagged as font operations are applied and 261p_pat is used for <test> elements with target=pattern. Returns FcFalse 262if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue. 263If <parameter>config</parameter> is NULL, the current configuration is used. 264@@ 265 266@RET@ FcBool 267@FUNC@ FcConfigSubstitute 268@TYPE1@ FcConfig * @ARG1@ config 269@TYPE2@ FcPattern * @ARG2@ p 270@TYPE3@ FcMatchKind% @ARG3@ kind 271@PURPOSE@ Execute substitutions 272@DESC@ 273Calls FcConfigSubstituteWithPat setting p_pat to NULL. Returns FcFalse 274if the substitution cannot be performed (due to allocation failure). Otherwise returns FcTrue. 275If <parameter>config</parameter> is NULL, the current configuration is used. 276@@ 277 278@RET@ FcPattern * 279@FUNC@ FcFontMatch 280@TYPE1@ FcConfig * @ARG1@ config 281@TYPE2@ FcPattern * @ARG2@ p 282@TYPE3@ FcResult * @ARG3@ result 283@PURPOSE@ Return best font 284@DESC@ 285Finds the font in <parameter>sets</parameter> most closely matching 286<parameter>pattern</parameter> and returns the result of 287<function>FcFontRenderPrepare</function> for that font and the provided 288pattern. This function should be called only after 289<function>FcConfigSubstitute</function> and 290<function>FcDefaultSubstitute</function> have been called for 291<parameter>p</parameter>; otherwise the results will not be correct. 292If <parameter>config</parameter> is NULL, the current configuration is used. 293@@ 294 295@RET@ FcFontSet * 296@FUNC@ FcFontSort 297@TYPE1@ FcConfig * @ARG1@ config 298@TYPE2@ FcPattern * @ARG2@ p 299@TYPE3@ FcBool% @ARG3@ trim 300@TYPE4@ FcCharSet ** @ARG4@ csp 301@TYPE5@ FcResult * @ARG5@ result 302@PURPOSE@ Return list of matching fonts 303@DESC@ 304Returns the list of fonts sorted by closeness to <parameter>p</parameter>. If <parameter>trim</parameter> is FcTrue, 305elements in the list which don't include Unicode coverage not provided by 306earlier elements in the list are elided. The union of Unicode coverage of 307all of the fonts is returned in <parameter>csp</parameter>, if <parameter>csp</parameter> is not NULL. This function 308should be called only after FcConfigSubstitute and FcDefaultSubstitute have 309been called for <parameter>p</parameter>; otherwise the results will not be correct. 310 </para><para> 311The returned FcFontSet references FcPattern structures which may be shared 312by the return value from multiple FcFontSort calls, applications must not 313modify these patterns. Instead, they should be passed, along with <parameter>p</parameter> to 314<function>FcFontRenderPrepare</function> which combines them into a complete pattern. 315 </para><para> 316The FcFontSet returned by FcFontSort is destroyed by calling FcFontSetDestroy. 317If <parameter>config</parameter> is NULL, the current configuration is used. 318@@ 319 320@RET@ FcPattern * 321@FUNC@ FcFontRenderPrepare 322@TYPE1@ FcConfig * @ARG1@ config 323@TYPE2@ FcPattern * @ARG2@ pat 324@TYPE3@ FcPattern * @ARG3@ font 325@PURPOSE@ Prepare pattern for loading font file 326@DESC@ 327Creates a new pattern consisting of elements of <parameter>font</parameter> not appearing 328in <parameter>pat</parameter>, elements of <parameter>pat</parameter> not appearing in <parameter>font</parameter> and the best matching 329value from <parameter>pat</parameter> for elements appearing in both. The result is passed to 330FcConfigSubstituteWithPat with <parameter>kind</parameter> FcMatchFont and then returned. 331@@ 332 333@RET@ FcFontSet * 334@FUNC@ FcFontList 335@TYPE1@ FcConfig * @ARG1@ config 336@TYPE2@ FcPattern * @ARG2@ p 337@TYPE3@ FcObjectSet * @ARG3@ os 338@PURPOSE@ List fonts 339@DESC@ 340Selects fonts matching <parameter>p</parameter>, creates patterns from those fonts containing 341only the objects in <parameter>os</parameter> and returns the set of unique such patterns. 342If <parameter>config</parameter> is NULL, the default configuration is checked 343to be up to date, and used. 344@@ 345 346@RET@ FcChar8 * 347@FUNC@ FcConfigFilename 348@TYPE1@ const FcChar8 * @ARG1@ name 349@PURPOSE@ Find a config file 350@DESC@ 351This function is deprecated and is replaced by <function>FcConfigGetFilename</function>. 352@@ 353 354@RET@ FcChar8 * 355@FUNC@ FcConfigGetFilename 356@TYPE1@ FcConfig * @ARG1@ config 357@TYPE2@ const FcChar8 * @ARG2@ name 358@PURPOSE@ Find a config file 359@DESC@ 360Given the specified external entity name, return the associated filename. 361This provides applications a way to convert various configuration file 362references into filename form. 363 </para><para> 364A null or empty <parameter>name</parameter> indicates that the default configuration file should 365be used; which file this references can be overridden with the 366FONTCONFIG_FILE environment variable. Next, if the name starts with <parameter>~</parameter>, it 367refers to a file in the current users home directory. Otherwise if the name 368doesn't start with '/', it refers to a file in the default configuration 369directory; the built-in default directory can be overridden with the 370FONTCONFIG_PATH environment variable. 371 </para><para> 372The result of this function is affected by the FONTCONFIG_SYSROOT environment variable or equivalent functionality. 373@@ 374 375@RET@ FcBool 376@FUNC@ FcConfigParseAndLoad 377@TYPE1@ FcConfig * @ARG1@ config 378@TYPE2@ const FcChar8 * @ARG2@ file 379@TYPE3@ FcBool% @ARG3@ complain 380@PURPOSE@ load a configuration file 381@DESC@ 382Walks the configuration in 'file' and constructs the internal representation 383in 'config'. Any include files referenced from within 'file' will be loaded 384and parsed. If 'complain' is FcFalse, no warning will be displayed if 385'file' does not exist. Error and warning messages will be output to stderr. 386Returns FcFalse if some error occurred while loading the file, either a 387parse error, semantic error or allocation failure. Otherwise returns FcTrue. 388@@ 389 390@RET@ FcBool 391@FUNC@ FcConfigParseAndLoadFromMemory 392@TYPE1@ FcConfig * @ARG1@ config 393@TYPE2@ const FcChar8 * @ARG2@ buffer 394@TYPE3@ FcBool% @ARG3@ complain 395@PURPOSE@ load a configuration from memory 396@DESC@ 397Walks the configuration in 'memory' and constructs the internal representation 398in 'config'. Any includes files referenced from within 'memory' will be loaded 399and dparsed. If 'complain' is FcFalse, no warning will be displayed if 400'file' does not exist. Error and warning messages will be output to stderr. 401Returns FcFalse if fsome error occurred while loading the file, either a 402parse error, semantic error or allocation failure. Otherwise returns FcTrue. 403@SINCE@ 2.12.5 404@@ 405 406@RET@ const FcChar8 * 407@FUNC@ FcConfigGetSysRoot 408@TYPE1@ const FcConfig * @ARG1@ config 409@PURPOSE@ Obtain the system root directory 410@DESC@ 411Obtains the system root directory in 'config' if available. All files 412(including file properties in patterns) obtained from this 'config' are 413relative to this system root directory. 414 </para><para> 415This function isn't MT-safe. <function>FcConfigReference</function> must be called 416before using this and then <function>FcConfigDestroy</function> when 417the return value is no longer referenced. 418@SINCE@ 2.10.92 419@@ 420 421@RET@ void 422@FUNC@ FcConfigSetSysRoot 423@TYPE1@ FcConfig * @ARG1@ config 424@TYPE2@ const FcChar8 * @ARG2@ sysroot 425@PURPOSE@ Set the system root directory 426@DESC@ 427Set 'sysroot' as the system root directory. All file paths used or created with 428this 'config' (including file properties in patterns) will be considered or 429made relative to this 'sysroot'. This allows a host to generate caches for 430targets at build time. This also allows a cache to be re-targeted to a 431different base directory if 'FcConfigGetSysRoot' is used to resolve file paths. 432When setting this on the current config this causes changing current config 433(calls FcConfigSetCurrent()). 434@SINCE@ 2.10.92 435@@ 436 437@RET@ void 438@FUNC@ FcConfigFileInfoIterInit 439@TYPE1@ FcConfig * @ARG1@ config 440@TYPE2@ FcConfigFileInfoIter * @ARG2@ iter 441@PURPOSE@ Initialize the iterator 442@DESC@ 443Initialize 'iter' with the first iterator in the config file information list. 444 </para><para> 445The config file information list is stored in numerical order for filenames 446i.e. how fontconfig actually read them. 447 </para><para> 448This function isn't MT-safe. <function>FcConfigReference</function> must be called 449before using this and then <function>FcConfigDestroy</function> when the relevant 450values are no longer referenced. 451@SINCE@ 2.12.91 452@@ 453 454@RET@ FcBool 455@FUNC@ FcConfigFileInfoIterNext 456@TYPE1@ FcConfig * @ARG1@ config 457@TYPE2@ FcConfigFileInfoIter * @ARG2@ iter 458@PURPOSE@ Set the iterator to point to the next list 459@DESC@ 460Set 'iter' to point to the next node in the config file information list. 461If there is no next node, FcFalse is returned. 462 </para><para> 463This function isn't MT-safe. <function>FcConfigReference</function> must be called 464before using <function>FcConfigFileInfoIterInit</function> and then 465<function>FcConfigDestroy</function> when the relevant values are no longer referenced. 466@SINCE@ 2.12.91 467@@ 468 469@RET@ FcBool 470@FUNC@ FcConfigFileInfoIterGet 471@TYPE1@ FcConfig * @ARG1@ config 472@TYPE2@ FcConfigFileInfoIter * @ARG2@ iter 473@TYPE3@ FcChar8 ** @ARG3@ name 474@TYPE4@ FcChar8 ** @ARG4@ description 475@TYPE5@ FcBool * @ARG5@ enabled 476@PURPOSE@ Obtain the configuration file information 477@DESC@ 478Obtain the filename, the description and the flag whether it is enabled or not 479for 'iter' where points to current configuration file information. 480If the iterator is invalid, FcFalse is returned. 481 </para><para> 482This function isn't MT-safe. <function>FcConfigReference</function> must be called 483before using <function>FcConfigFileInfoIterInit</function> and then 484<function>FcConfigDestroy</function> when the relevant values are no longer referenced. 485@SINCE@ 2.12.91 486@@ 487