diff options
Diffstat (limited to 'app/xfs/xfs.man')
| -rw-r--r-- | app/xfs/xfs.man | 469 |
1 files changed, 300 insertions, 169 deletions
diff --git a/app/xfs/xfs.man b/app/xfs/xfs.man index 1a5cd11bc..4f71ce2e4 100644 --- a/app/xfs/xfs.man +++ b/app/xfs/xfs.man @@ -37,206 +37,337 @@ .\" suitability of this software for any purpose. It is provided "as is" .\" without express or implied warranty. .\" $Xorg: xfs.man,v 1.4 2001/02/09 02:05:42 xorgcvs Exp $ -.TH XFS 1 __xorgversion__ +.TH xfs __appmansuffix__ __xorgversion__ .SH NAME xfs \- X font server .SH SYNOPSIS -.B "xfs" -[\-config \fIconfiguration_file\fP] -[\-daemon] -[\-droppriv] -[\-ls \fIlisten_socket\fP] -[\-nodaemon] -[\-port \fItcp_port\fP] -[\-user \fIusername\fP] +.B xfs +[ +.BI "\-config " configuration_file +] +[ +.B \-daemon +] +[ +.B \-droppriv +] +[ +.BI "\-ls " listen_socket +] +[ +.B \-nodaemon +] +[ +.BI "\-port " tcp_port +] +[ +.BI "\-user " username +] .SH DESCRIPTION +.B xfs +is the X Window System font server. +It supplies fonts to X Window System display servers. +The server is usually run by a system administrator, and started via +.BR init (__adminmansuffix__). +Users may also wish to start private font servers for specific sets of +fonts. .PP -.I Xfs -is the X Window System font server. It supplies fonts to X Window -System display servers. -.SH "STARTING THE SERVER" -The server is usually run by a system administrator, and started via -boot files like \fI/etc/rc.local\fR. Users may also wish to start -private font servers for specific sets of fonts. -.SH "OPTIONS" -.TP 8 -.B \-config configuration_file -Specifies the configuration file the font server will use. If this -parameter is not specified, the default file, \fI__configdir__/config\fR -will be used. -.TP 8 -.B \-ls listen_socket -Specifies a file descriptor which is already set up to be used as the -listen socket. This option is only intended to be used by the font server -itself when automatically spawning another copy of itself to handle -additional connections. -.TP 8 -.B \-port tcp_port -Specifies the TCP port number on which the server will listen for connections. -The default port number is 7100. -.TP 8 +To connect to a font server, see the documentation for your X server; it +likely supports the syntax documented in the \(lqFONT SERVER NAMES\(rq +section of +.BR X (__miscmansuffix__). +.SH OPTIONS +.TP +.BI "\-config " configuration_file +specifies the configuration file +.B xfs +will use. +If this parameter is not specified, xfs will read its configuration from +__configfiledesc__ \fI__configfilepath__\fR. +.TP .B \-daemon -Instructs xfs to fork and go into the background automatically at -startup If this option is not specified, xfs will run as a regular -process (unless xfs was built to daemonize by default). -.TP 8 +instructs +.B xfs +to fork and go into the background automatically at startup. +If this option is not specified, +.B xfs +will run as a regular process (unless it was built to daemonize by +default). +When running as a daemon, +.B xfs +will attempt to create a file in which it stores its process ID, and will +delete that file upon exit; +.TP .B \-droppriv -If specified, xfs will attempt to run as user and group \fIxfs\fR (unless -the +instructs +.B xfs +to attempt to run as user and group +.I xfs +(unless the .B \-user -option is used). This -has been implemented for security reasons, as xfs may have undiscovered -buffer overflows or other paths for possible exploit, both local and -remote. With this option, you may also wish to specify -"no-listen = tcp" -in the config file, which ensures that xfs will not to use a TCP port at all. -.TP 8 +option is used). +This has been implemented for security reasons, as +.B xfs +may have undiscovered buffer overflows or other paths for possible exploit, +both local and remote. +When using this option, you may also wish to specify \(oqno\-listen = +tcp\(cq in the config file, which ensures that +.B xfs +will not to use a TCP port at all. +By default, +.B xfs +runs with the user and group IDs of the user who invoked it. +.TP +.BI "\-ls " listen_socket +specifies a file descriptor which is already set up to be used as the +listen socket. +This option is only intended to be used by the font server itself when +automatically spawning another copy of itself to handle additional +connections. +.TP .B \-nodaemon -When xfs is built to daemonize (run in the background) by default, -this prevents that and starts xfs up as a regular process. -.TP 8 -.B \-user username -This is equivalent to +instructs +.B xfs +not to daemonize (fork and detach from its controlling terminal). +This option only has an effect if +.B xfs +is built to daemonize by default, which is not the stock configuration. +.TP +.BI "\-port " tcp_port +specifies the TCP port number on which the server will listen for +connections. +The default port number is 7100. +This option is ignored if +.B xfs +is configured to not listen to TCP transports at all (see \(lqConfiguration +File Format\(rq below). +.TP +.BI "\-user " username +instructs +.B xfs +to run as the user +.IR username. +See .B \-droppriv -except that xfs will run as user \fIusername\fR. -.SH "SIGNALS" -.TP 8 -.I SIGTERM -This causes the font server to exit cleanly. -.TP 8 -.I SIGUSR1 -This signal is used to cause the server to re-read its configuration file. -.TP 8 -.I SIGUSR2 -This signal is used to cause the server to flush any cached data it -may have. -.TP 8 -.I SIGHUP -This signal is used to cause the server to reset, closing all active -connections and re-reading the configuration file. -.SH "CONFIGURATION" +for why this may be desired. +By default, +.B xfs +runs with the user and group IDs of the user who invoked it. +.SH "INPUT FILES" +.B xfs +reads and serves any font file format recognized by the X server itself. +It locates font files through the specification of a +.IR catalogue , +which is declared in +.BR xfs 's +configuration file. +.SS "Configuration File Format" +.B xfs +reads its configuration from a text file (see the +.B \-config +option in the \(lqOPTIONS\(rq section above). The configuration language is a list of keyword and value pairs. -Each keyword is followed by an '=' and then the desired value. +Each keyword is followed by an equals sign (\(oq=\(cq) and then the desired +value. .PP Recognized keywords include: -.sp -.\" .IP "cache-size (cardinal)" -.\" Size in bytes of the font server cache. -.IP "catalogue (list of string)" -Ordered list of font path element names. -Use of the keyword "catalogue" is very misleading at present, -the current implementation only supports a single catalogue ("all"), -containing all of the specified fonts. -.IP "alternate-servers (list of string)" -List of alternate servers for this font server. -.IP "client-limit (cardinal)" -Number of clients this font server will support -before refusing service. This is useful for tuning -the load on each individual font server. -.IP "clone-self (boolean)" -Whether this font server should attempt to clone itself -when it reachs the client-limit. -.IP "default-point-size (cardinal)" -The default pointsize (in decipoints) for fonts that -don't specify. The default is 120. -.IP "default-resolutions (list of resolutions)" -Resolutions the server supports by default. -This information may be used as a hint for -pre-rendering, and substituted for scaled fonts -which do not specify a resolution. -A resolution is a comma-separated pair of x and y resolutions in -pixels per inch. +.TP +.BR alternate\-servers " (list of \fIstring\fPs)" +lists alternate servers for this font server. +See the \(lqFONT SERVER NAMES\(rq section of +.BR X (__miscmansuffix__) +for the syntax of the string. +.\" .TP +.\" .BR cache\-size " (\fIcardinal\fP)" +.\" determines the size (in bytes) of the font server cache. +.TP +.BR catalogue " (list of \fIstring\fPs)" +declares as ordered list of font path element names from which fonts will +be served. +The current implementation only supports a single catalogue ("all") +containing all of the specified fonts. A special directory with +symlinks to font paths can be specified using a catalogue:<dir> +entry. See the CATALOGUE DIR section below for details. +.TP +.BR client\-limit " (\fIcardinal\fP)" +determines the number of clients this font server will support before +refusing service. +This is useful for tuning the load on each individual font server. +.TP +.BR clone\-self " (\fIboolean\fP)" +indicates whether this font server should attempt to clone itself when the +number of connected clients reaches the +.BR client\-limit . +.TP +.BR default\-point\-size " (\fIcardinal\fP)" +The default pointsize (in decipoints) for font requests that don't specify +a point size. +The default is 120. +.TP +.BR default\-resolutions " (list of \fIresolution\fPs)" +indicates the resolutions the server supports by default. +This information may be used as a hint for pre-rendering, and substituted +into requests for scaled fonts which do not specify a resolution. +A +.I resolution +is a comma-separated pair of horizontal and vertical resolutions in pixels +per inch. Multiple resolutions are separated by commas. -.IP "error-file (string)" -Filename of the error file. All warnings and errors -will be logged here. -.IP "no-listen (trans-type)" -Disable a transport type. For example, TCP/IP connections can -be disabled with no-listen tcp -.IP "port (cardinal)" -TCP port on which the server will listen for connections. -.IP "use-syslog (boolean)" -Whether syslog(3) (on supported systems) is to be used -for errors. -.IP "deferglyphs (string)" -Set the mode for delayed fetching and caching of glyphs. Value is -"none", meaning deferred glyphs is disabled, "all", meaning it is -enabled for all fonts, and "16", meaning it is enabled only for -16-bits fonts. -.\" .IP "trusted-clients (list of string)" -.\" Those clients the fontserver will talk to. Others -.\" will be refused for the initial connection. An empty -.\" list means the server will talk to any client. -.SH "EXAMPLE" +.TP +.BR deferglyphs " (\fIstring\fP)" +sets the mode for delayed fetching and caching of glyphs. +.I string +should be one of \(oqnone\(cq, meaning glyphs deferment is disabled, +\(oqall\(cq, meaning it is enabled for all fonts, and \(oq16\(cq, meaning +it is enabled only for 16-bit fonts. +.TP +.BR error\-file " (\fIstring\fP)" +indicates the filename of the error file. +All warnings and errors will be logged here, unless +.B use\-syslog +is set to a true value (see below). +.TP +.BR no\-listen " (\fItrans-type\fP)" +disables the specified transport type. +For example, TCP/IP connections can be disabled with \(oqno\-listen = +tcp\(cq. +.TP +.BR port " (\fIcardinal\fP)" +indicates the TCP port on which the server will listen for connections. +.\" .TP +.\" .BR trusted-clients " (list of \fIstring\fPs)" +.\" identifies the clients the font server will talk to. +.\" Others will be refused for the initial connection. +.\" An empty list means the server will talk to any client. +.TP +.BR use\-syslog " (\fIboolean\fP)" +determines whether errors and diagnostics should be reported via +.BR syslog (__libmansuffix__) +(on supported systems) instead of being written to the +.B error\-file +(see above). +.SH "CATALOGUE DIR" +You can specify a special kind of font path in the form \fBcatalogue:<dir>\fR. +The directory specified after the catalogue: prefix will be scanned for symlinks +and each symlink destination will be added as a local fontfile FPE. +.PP +The symlink can be suffixed by attributes such as '\fBunscaled\fR', which +will be passed through to the underlying fontfile FPE. The only exception is +the newly introduced '\fBpri\fR' attribute, which will be used for ordering +the font paths specified by the symlinks. + +An example configuration: + +.nf + 75dpi:unscaled:pri=20 \-> /usr/share/X11/fonts/75dpi + ghostscript:pri=60 \-> /usr/share/fonts/default/ghostscript + misc:unscaled:pri=10 \-> /usr/share/X11/fonts/misc + type1:pri=40 \-> /usr/share/X11/fonts/Type1 + type1:pri=50 \-> /usr/share/fonts/default/Type1 +.fi + +This will add /usr/share/X11/fonts/misc as the first FPE with the attribute +'unscaled', second FPE will be /usr/share/X11/fonts/75dpi, also with +the attribute unscaled etc. This is functionally equivalent to setting +the following font path: + +.nf + /usr/share/X11/fonts/misc:unscaled, + /usr/share/X11/fonts/75dpi:unscaled, + /usr/share/X11/fonts/Type1, + /usr/share/fonts/default/Type1, + /usr/share/fonts/default/ghostscript +.fi +.SS "Example Configuration File" .nf XCOMM XCOMM sample font server configuration file XCOMM -XCOMM allow a max of 10 clients to connect to this font server -client-limit = 10 +XCOMM allow a max of 10 clients to connect to this font server. +client\-limit = 10 -XCOMM when a font server reaches its limit, start up a new one -clone-self = on +XCOMM When a font server reaches the above limit, start up a new one. +clone\-self = on -XCOMM alternate font servers for clients to use -alternate-servers = hansen:7101,hansen:7102 +XCOMM Identify alternate font servers for clients to use. +alternate\-servers = hansen:7101,hansen:7102 -XCOMM where to look for fonts -XCOMM the first is a set of Speedo outlines, the second is a set of -XCOMM misc bitmaps and the last is a set of 100dpi bitmaps +XCOMM Look for fonts in the following directories. The first is a set of +XCOMM TrueType outlines, the second is a set of misc bitmaps (such as terminal +XCOMM and cursor fonts), and the last is a set of 100dpi bitmaps. XCOMM -catalogue = /usr/X11R6/lib/X11/fonts/speedo, - /usr/X11R6/lib/X11/fonts/misc, - /usr/X11R6/lib/X11/fonts/100dpi/ +catalogue = /usr/X11R6/lib/X11/fonts/TTF, + /usr/X11R6/lib/X11/fonts/misc, + /usr/X11R6/lib/X11/fonts/100dpi/ XCOMM in 12 points, decipoints -default-point-size = 120 +default\-point\-size = 120 XCOMM 100 x 100 and 75 x 75 -default-resolutions = 100,100,75,75 -use-syslog = off -.fi -.sp -.SH "FONT SERVER NAMES" -One of the following forms can be used to name a font server that -accepts TCP connections: -.sp -.nf - tcp/\fIhostname\fP:\fIport\fP - tcp/\fIhostname\fP:\fIport\fP/\fIcataloguelist\fP -.fi -.PP -The \fIhostname\fP specifies the name (or decimal numeric address) -of the machine on which the font server is running. The \fIport\fP -is the decimal TCP port on which the font server is listening for connections. -The \fIcataloguelist\fP specifies a list of catalogue names, -with '+' as a separator. -.PP -Examples: \fItcp/fs.x.org:7100\fP, \fItcp/18.30.0.212:7101/all\fP. -.PP -One of the following forms can be used to name a font server that -accepts DECnet connections: -.sp -.nf - decnet/\fInodename\fP::font$\fIobjname\fP - decnet/\fInodename\fP::font$\fIobjname\fP/\fIcataloguelist\fP +default\-resolutions = 100,100,75,75 + +XCOMM Specify our log filename. +error\-file = /var/log/xfs.log + +XCOMM Direct diagnostics to our own log file instead of using syslog. +use\-syslog = off .fi -.PP -The \fInodename\fP specifies the name (or decimal numeric address) -of the machine on which the font server is running. -The \fIobjname\fP is a normal, case-insensitive DECnet object name. -The \fIcataloguelist\fP specifies a list of catalogue names, -with '+' as a separator. -.PP -Examples: \fIDECnet/SRVNOD::FONT$DEFAULT\fP, \fIdecnet/44.70::font$special/symbols\fP. -.SH "SEE ALSO" -X(__miscmansuffix__), \fIThe X Font Service Protocol\fP, -.br -\fIFont server implementation overview\fP +.SH "OUTPUT FILES" +When operating in daemon mode, +.B xfs +sends diagnostic messages (errors and warnings) to the system log via the +.B syslog +C library function by default. +However, these messages can be sent to an alternate location via the +.B error\-file +and +.B use\-syslog +configuration variables; see \(lqConfiguration File Format\(rq, above. +.SH "ASYNCHRONOUS EVENTS" +.B xfs +handles the following signals specially: +.TP +.I SIGTERM +causes the font server to exit cleanly. +.TP +.I SIGUSR1 +causes +.B xfs +to re-read its configuration file. +.TP +.I SIGUSR2 +causes +.B xfs +to flush any cached data it may have. +.TP +.I SIGHUP +causes +.B xfs +to reset, closing all active connections and re-reading the configuration +file. .SH BUGS Multiple catalogues should be supported. +.SH "FUTURE DIRECTIONS" +Significant further development of +.B xfs +is unlikely. +One of the original motivations behind it was the single-threaded nature of +the X server \(em a user's X session could seem to \(oqfreeze up\(cq while +the X server took a moment to rasterize a font. +This problem with the X server, which remains single-threaded in all +popular implementations to this day, has been mitigated on two fronts: +machines have gotten much faster, and client-side font rendering +(particularly via the Xft library) is the norm in contemporary software. .SH AUTHORS Dave Lemke, Network Computing Devices, Inc .br Keith Packard, Massachusetts Institute of Technology +.SH "SEE ALSO" +.BR X (__miscmansuffix__), +.BR xfsinfo (__appmansuffix__), +.BR fslsfonts (__appmansuffix__), +.BR init (__adminmansuffix__), +.BR syslog (__libmansuffix__), +.IR "The X Font Service Protocol" , +.I Font Server Implementation Overview |