Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       fonts.conf - Font configuration files


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

       Fontconfig contains two essential  modules,  the	 configuration	module
       which  builds an	internal configuration from XML	files and the matching
       module which accepts font patterns and  returns	the  nearest  matching

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

       The intent is to	make font configurations relatively static, and	shared
       by as many applications as possible.  It	is hoped that this  will  lead
       to  more	 stable	font selection when passing names from one application
       to another.  XML	was chosen as a	configuration file format  because  it
       provides	 a  format which is easy for external agents to	edit while re-
       taining the correct structure and syntax.

       Font configuration is separate from font	matching; applications needing
       to  do  their  own matching can access the available fonts from the li-
       brary and perform private matching.  The	intent is to  permit  applica-
       tions to	pick and choose	appropriate functionality from the library in-
       stead of	forcing	them to	choose between this library and	a private con-
       figuration  mechanism.  The hope	is that	this will ensure that configu-
       ration of fonts for all applications can	be centralized in  one	place.
       Centralizing  font  configuration will simplify and regularize font in-
       stallation and customization.

       While font patterns may contain essentially any properties,  there  are
       some well known properties with associated types.  Fontconfig uses some
       of these	properties for font matching and font completion.  Others  are
       provided	as a convenience for the applications' rendering mechanism.

	 Property	 Type	 Description
	 family		 String	 Font family names
	 familylang	 String	 Languages corresponding to each family
	 style		 String	 Font style. Overrides weight and slant
	 stylelang	 String	 Languages corresponding to each style
	 fullname	 String	 Font full names (often	includes style)
	 fullnamelang	 String	 Languages corresponding to each fullname
	 slant		 Int	 Italic, oblique or roman
	 weight		 Int	 Light,	medium,	demibold, bold or black
	 size		 Double	 Point size
	 width		 Int	 Condensed, normal or expanded
	 aspect		 Double	 Stretches glyphs horizontally before hinting
	 pixelsize	 Double	 Pixel size
	 spacing	 Int	 Proportional, dual-width, monospace or	charcell
	 foundry	 String	 Font foundry name
	 antialias	 Bool	 Whether glyphs	can be antialiased
	 hinting	 Bool	 Whether the rasterizer	should use hinting
	 hintstyle	 Int	 Automatic hinting style
	 verticallayout	 Bool	 Use vertical layout
	 autohint	 Bool	 Use autohinter	instead	of normal hinter
	 globaladvance	 Bool	 Use font global advance data
	 file		 String	 The filename holding the font
	 index		 Int	 The index of the font within the file
	 ftface		 FT_Face Use the specified FreeType face object
	 rasterizer	 String	 Which rasterizer is in	use
	 outline	 Bool	 Whether the glyphs are	outlines
	 scalable	 Bool	 Whether glyphs	can be scaled
	 scale		 Double	 Scale factor for point->pixel conversions
	 dpi		 Double	 Target	dots per inch
	 rgba		 Int	 unknown, rgb, bgr, vrgb, vbgr,
				 none -	subpixel geometry
	 lcdfilter	 Int	 Type of LCD filter
	 minspace	 Bool	 Eliminate leading from	line spacing
	 charset	 CharSet Unicode chars encoded by the font
	 lang		 String	 List of RFC-3066-style	languages this
				 font supports
	 fontversion	 Int	 Version number	of the font
	 capability	 String	 List of layout	capabilities in	the font
	 embolden	 Bool	 Rasterizer should synthetically embolden the font

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

       Font  matching starts with an application constructed pattern.  The de-
       sired attributes	of the resulting font are collected together in	a pat-
       tern.   Each  property  of  the pattern can contain one or more values;
       these are listed	in priority order; matches earlier  in	the  list  are
       considered "closer" than	matches	later in the list.

       The  initial  pattern  is  modified by applying the list	of editing in-
       structions specific to patterns found in	the configuration;  each  con-
       sists  of  a match predicate and	a set of editing operations.  They are
       executed	in the order they appeared in the configuration.   Each	 match
       causes the associated sequence of editing operations to be applied.

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

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

       There is	one special case to this rule; family names are	split into two
       bindings; strong	and weak.   Strong  family  names  are	given  greater
       precedence  in the match	than lang elements while weak family names are
       given lower precedence than lang	elements.  This	permits	 the  document
       language	 to  drive  font selection when	any document specified font is

       The pattern representing	that font is augmented to include any  proper-
       ties  found  in the pattern but not found in the	font itself; this per-
       mits the	application to pass rendering instructions or any  other  data
       through the matching system.  Finally, the list of editing instructions
       specific	to fonts found in the configuration are	applied	 to  the  pat-
       tern.  This modified pattern is returned	to the application.

       The  return value contains sufficient information to locate and raster-
       ize the font, including the file	name, pixel size and  other  rendering
       data.  As none of the information involved pertains to the FreeType li-
       brary, applications are free to use any rasterization engine or even to
       take the	identified font	file and access	it directly.

       The  match/edit	sequences  in  the  configuration are performed	in two
       passes because there are	essentially two	different operations necessary
       -- the first is to modify how fonts are selected; aliasing families and
       adding suitable defaults.  The second is	to  modify  how	 the  selected
       fonts  are  rasterized.	Those must apply to the	selected font, not the
       original	pattern	as false matches will often occur.

       Fontconfig provides a textual representation for	patterns that the  li-
       brary  can  both	 accept	 and generate.	The representation is in three
       parts, first a list of family names, second a list of point  sizes  and
       finally a list of additional properties:

	    <families>-<point sizes>:<name1>=<values1>:<name2>=<values2>...

       Values  in  a list are separated	with commas.  The name needn't include
       either families or point	sizes; they can	be elided.  In addition, there
       are  symbolic  constants	that simultaneously indicate both a name and a
       value.  Here are	some examples:

	 Name				 Meaning
	 Times-12			 12 point Times	Roman
	 Times-12:bold			 12 point Times	Bold
	 Courier:italic			 Courier Italic	in the default size
	 Monospace:matrix=1 .1 0 1	 The users preferred monospace font
					 with artificial obliquing

       The '\',	'-', ':' and ',' characters in family names must be  preceeded
       by a '\'	character to avoid having them misinterpreted. Similarly, val-
       ues containing '\', '=',	'_', ':' and ',' must also have	them preceeded
       by  a  '\' character. The '\' characters	are stripped out of the	family
       name and	values as the font name	is read.

       To help diagnose	font and applications problems,	 fontconfig  is	 built
       with  a	large  amount  of  internal debugging left enabled. It is con-
       trolled by means	of the FC_DEBUG	environment  variable.	The  value  of
       this  variable  is  interpreted	as  a number, and each bit within that
       value controls different	debugging messages.

	 Name	      Value    Meaning
	 MATCH		  1    Brief information about font matching
	 MATCHV		  2    Extensive font matching information
	 EDIT		  4    Monitor match/test/edit execution
	 FONTSET	  8    Track loading of	font information at startup
	 CACHE		 16    Watch cache files being written
	 CACHEV		 32    Extensive cache file writing information
	 PARSE		 64    (no longer in use)
	 SCAN		128    Watch font files	being scanned to build caches
	 SCANV		256    Verbose font file scanning information
	 MEMORY		512    Monitor fontconfig memory usage
	 CONFIG	       1024    Monitor which config files are loaded
	 LANGSET       2048    Dump char sets used to construct	lang values
	 OBJTYPES      4096    Display message when value typechecks fail

       Add the value of	the desired debug levels together and assign that  (in
       base 10)	to the FC_DEBUG	environment variable before running the	appli-
       cation. Output from these statements is sent to stdout.

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

       Fontconfig  has	orthographies for several languages built into the li-
       brary.  No provision has	been made for adding new ones aside  from  re-
       building	 the  library.	It currently supports 122 of the 139 languages
       named in	ISO 639-1, 141 of the languages	with two-letter	codes from ISO
       639-2 and another 30 languages with only	three-letter codes.  Languages
       with both two and three letter codes are	provided  with	only  the  two
       letter code.

       For  languages  used  in	 multiple territories with radically different
       character sets, fontconfig includes per-territory orthographies.	  This
       includes	Azerbaijani, Kurdish, Pashto, Tigrinya and Chinese.

       Configuration  files for	fontconfig are stored in XML format; this for-
       mat makes external configuration	tools easier to	write and ensures that
       they  will  generate syntactically correct configuration	files.	As XML
       files are plain text, they can also be manipulated by the  expert  user
       using a text editor.

       The  fontconfig document	type definition	resides	in the external	entity
       "fonts.dtd"; this is normally stored in the default font	 configuration
       directory  (/etc/fonts).	  Each	configuration  file should contain the
       following structure:

	    <?xml version="1.0"?>
	    <!DOCTYPE fontconfig SYSTEM	"fonts.dtd">

       This is the top level element for a font	configuration and can  contain
       <dir>, <cache>, <include>, <match> and <alias> elements in any order.

       This  element  contains a directory name	which will be scanned for font
       files to	include	in the set of available	fonts.

       This element contains a file name for the per-user cache	of font	infor-
       mation.	 If  it	starts with '~', it refers to a	file in	the users home
       directory.  This	file is	used to	 hold  information  about  fonts  that
       isn't  present  in  the per-directory cache files.  It is automatically
       maintained by the fontconfig library.  The default  for	this  file  is
       ``~/.fonts.cache-<version>'', where <version> is	the font configuration
       file version number (currently 2).

       This element contains the name of an additional configuration  file  or
       directory.   If	a directory, every file	within that directory starting
       with an ASCII digit (U+0030  -  U+0039)	and  ending  with  the	string
       ``.conf''  will be processed in sorted order.  When the XML datatype is
       traversed by FcConfigParse, the contents	of the file(s)	will  also  be
       incorporated  into  the configuration by	passing	the filename(s)	to Fc-
       ConfigLoadAndParse.  If 'ignore_missing'	is set to "yes"	instead	of the
       default	"no",  a missing file or directory will	elicit no warning mes-
       sage from the library.

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

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

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

       This element is used to black/white list	fonts  from  being  listed  or
       matched against.	 It holds acceptfont and rejectfont elements.

       Fonts  matched  by  an acceptfont element are "whitelisted"; such fonts
       are explicitly included in the set of fonts used	to  resolve  list  and
       match  requests;	 including  them in this list protects them from being
       "blacklisted" by	a rejectfont  element.	 Acceptfont  elements  include
       glob and	pattern	elements which are used	to match fonts.

       Fonts  matched  by  an rejectfont element are "blacklisted"; such fonts
       are excluded from the set of fonts used to resolve list and  match  re-
       quests  as if they didn't exist in the system.  Rejectfont elements in-
       clude glob and pattern elements which are used to match fonts.

       Glob elements hold shell-style filename matching	patterns (including  ?
       and  *)	which match fonts based	on their complete pathnames.  This can
       be used to exclude a set	of  directories	 (/usr/share/fonts/uglyfont*),
       or  particular font file	types (*.pcf.gz), but the latter mechanism re-
       lies rather heavily on filenaming conventions  which  can't  be	relied
       upon.   Note  that  globs  only apply to	directories, not to individual

       Pattern elements	perform	list-style matching on	incoming  fonts;  that
       is,  they  hold	a  list	 of elements and associated values.  If	all of
       those elements have a matching value,  then  the	 pattern  matches  the
       font.  This can be used to select fonts based on	attributes of the font
       (scalable, bold,	etc), which is a more reliable	mechanism  than	 using
       file extensions.	 Pattern elements include patelt elements.

       Patelt elements hold a single pattern element and list of values.  They
       must have a 'name' attribute which indicates the	pattern	element	 name.
       Patelt  elements	include	int, double, string, matrix, bool, charset and
       const elements.

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

       This element contains a single value which is compared with the	target
       ('pattern',  'font',  'scan' or 'default') property "property" (substi-
       tute any	of the property	names seen above). 'compare'  can  be  one  of
       "eq",  "not_eq",	 "less",  "less_eq", "more", or	"more_eq".  'qual' may
       either be the default, "any", in	which case the match succeeds  if  any
       value associated	with the property matches the test value, or "all", in
       which case all of the values associated with the	 property  must	 match
       the test	value.	When used in a <match target="font"> element, the tar-
       get= attribute in the <test> element selects between matching the orig-
       inal pattern or the font.  "default" selects whichever target the outer
       <match> element has selected.

       This element contains a list of expression elements (any	of  the	 value
       or  operator  elements).	 The expression	elements are evaluated at run-
       time and	modify the property "property".	 The modification  depends  on
       whether	"property"  was	 matched  by one of the	associated <test> ele-
       ments, if so, the modification may affect the first matched value.  Any
       values  inserted	 into  the  property  are  given the indicated binding
       ("strong", "weak" or "same") with "same"	binding	using the  value  from
       the matched pattern element.  'mode' is one of:

	 Mode			 With Match		 Without Match
	 "assign"		 Replace matching value	 Replace all values
	 "assign_replace"	 Replace all values	 Replace all values
	 "prepend"		 Insert	before matching	 Insert	at head	of list
	 "prepend_first"	 Insert	at head	of list	 Insert	at head	of list
	 "append"		 Append	after matching	 Append	at end of list
	 "append_last"		 Append	at end of list	 Append	at end of list

       These  elements hold a single value of the indicated type.  <bool> ele-
       ments hold either true or false.	 An important limitation exists	in the
       parsing	of floating point numbers -- fontconfig	requires that the man-
       tissa start with	a digit, not a decimal point, so insert	a leading zero
       for  purely  fractional values (e.g. use	0.5 instead of .5 and -0.5 in-
       stead of	-.5).

       This element holds the four <double> elements of	an affine  transforma-

       Holds  a	property name.	Evaluates to the first value from the property
       of the font, not	the pattern.

       Holds the name of a constant; these are always integers	and  serve  as
       symbolic	names for common font values:

	 Constant	 Property	 Value
	 thin		 weight		 0
	 extralight	 weight		 40
	 ultralight	 weight		 40
	 light		 weight		 50
	 book		 weight		 75
	 regular	 weight		 80
	 normal		 weight		 80
	 medium		 weight		 100
	 demibold	 weight		 180
	 semibold	 weight		 180
	 bold		 weight		 200
	 extrabold	 weight		 205
	 black		 weight		 210
	 heavy		 weight		 210
	 roman		 slant		 0
	 italic		 slant		 100
	 oblique	 slant		 110
	 ultracondensed	 width		 50
	 extracondensed	 width		 63
	 condensed	 width		 75
	 semicondensed	 width		 87
	 normal		 width		 100
	 semiexpanded	 width		 113
	 expanded	 width		 125
	 extraexpanded	 width		 150
	 ultraexpanded	 width		 200
	 proportional	 spacing	 0
	 dual		 spacing	 90
	 mono		 spacing	 100
	 charcell	 spacing	 110
	 unknown	 rgba		 0
	 rgb		 rgba		 1
	 bgr		 rgba		 2
	 vrgb		 rgba		 3
	 vbgr		 rgba		 4
	 none		 rgba		 5
	 lcdnone	 lcdfilter	 0
	 lcddefault	 lcdfilter	 1
	 lcdlight	 lcdfilter	 2
	 lcdlegacy	 lcdfilter	 3
	 hintnone	 hintstyle	 0
	 hintslight	 hintstyle	 1
	 hintmedium	 hintstyle	 2
	 hintfull	 hintstyle	 3

   <OR>, <AND>,	<PLUS>,	<MINUS>, <TIMES>, <DIVIDE>
       These  elements perform the specified operation on a list of expression
       elements.  <or> and <and> are boolean, not bitwise.

   <EQ>, <NOT_EQ>, <LESS>, <LESS_EQ>, <MORE>, <MORE_EQ>
       These elements compare two values, producing a boolean result.

       Inverts the boolean sense of its	one expression element

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

       Alias elements provide a	shorthand notation for the set of common match
       operations needed to substitute one font	family for another.  They con-
       tain a <family> element followed	by  optional  <prefer>,	 <accept>  and
       <default>  elements.  Fonts matching the	<family> element are edited to
       prepend the list	of <prefer>ed families before the  matching  <family>,
       append the <accept>able families	after the matching <family> and	append
       the <default> families to the end of the	family list.

       Holds a single font family name

       These hold a list of <family> elements to be used by the	 <alias>  ele-

       This is an example of a system-wide configuration file

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

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

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

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

	    Load local customization files, but	don't complain
	    if there aren't any
       <include	ignore_missing="yes">conf.d</include>
       <include	ignore_missing="yes">local.conf</include>

	    Alias well known font names	to available TrueType fonts.
	    These substitute TrueType faces for	similar	Type1
	    faces to improve screen appearance.
	    <prefer><family>Times New Roman</family></prefer>
	    <prefer><family>Courier New</family></prefer>

	    Provide required aliases for standard names
	    Do these after the users configuration file	so that
	    any	aliases	there are used preferentially
	    <prefer><family>Times New Roman</family></prefer>
	    <prefer><family>Andale Mono</family></prefer>

       This  is	 an  example  of  a  per-user configuration file that lives in

       <?xml version="1.0"?>
       <!DOCTYPE fontconfig SYSTEM "fonts.dtd">
       <!-- ~/.fonts.conf for per-user font configuration -->

	    Private font directory

	    use	rgb sub-pixel ordering to improve glyph	appearance on
	    LCD	screens.  Changes affecting rendering, but not matching
	    should always use target="font".
       <match target="font">
	    <edit name="rgba" mode="assign"><const>rgb</const></edit>

       fonts.conf contains configuration information for  the  fontconfig  li-
       brary consisting	of directories to look at for font information as well
       as instructions on editing program specified font patterns  before  at-
       tempting	to match the available fonts.  It is in	xml format.

       conf.d  is the conventional name	for a directory	of additional configu-
       ration files managed by external	applications or	the local  administra-
       tor.   The filenames starting with decimal digits are sorted in lexico-
       graphic order and used as additional configuration files.  All of these
       files  are  in  xml format.  The	master fonts.conf file references this
       directory in an <include> directive.

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

       ~/.fonts.conf is	the conventional location for per-user font configura-
       tion,  although	the  actual  location  is  specified  in  the	global
       fonts.conf file.

	~/.fonts.cache-*  is  the  conventional	repository of font information
       that isn't found	in the per-directory caches.  This file	 is  automati-
       cally maintained	by fontconfig.

       fc-cache(1), fc-match(1), fc-list(1)

       Fontconfig version 2.6.0

				  31 May 2008			 FONTS-CONF(5)


Want to link to this manual page? Use this URL:

home | help