Skip to content

GitLab

Commit d98bd4bf authored by Branden Robinson's avatar Branden Robinson Committed by David Nusinow
Browse files
Options

Overhaul xorg.conf manpage 

Major stylistic cleanups, greatly expanded cross-reference ("SEE ALSO")
section and some typo fixes.

This patch by Branden Robinson. Forward-ported by Fabio M. Di Nitto.
parent 6bf8d501
Hide whitespace changes
Inline Side-by-side
Showing with 743 additions and 547 deletions
hw/xfree86/doc/man/xorg.conf.man.pre
View file @ d98bd4bf
......@@ -3,7 +3,7 @@
.ds q \N'34'
.TH __xconfigfile__ __filemansuffix__ __vendorversion__
.SH NAME
__xconfigfile__ - Configuration File for __xservername__
__xconfigfile__ \- configuration File for __xservername__ X server
.SH INTRODUCTION
.B __xservername__
supports several mechanisms for supplying/obtaining configuration and
......@@ -21,9 +21,10 @@ manual page.
.SH DESCRIPTION
.B __xservername__
uses a configuration file called
.B __xconfigfile__
for its initial setup. This configuration file is searched for in the
following places when the server is started as a normal user:
.I __xconfigfile__
for its initial setup.
This configuration file is searched for in the following places when the
server is started as a normal user:
.PP
.RS 4
.nf
......@@ -31,30 +32,31 @@ following places when the server is started as a normal user:
.IR __projectroot__/etc/X11/ <cmdline>
.IB /etc/X11/ $XORGCONFIG
.IB __projectroot__/etc/X11/ $XORGCONFIG
.I /etc/X11/__xconfigfile__-4
.I /etc/X11/__xconfigfile__\-4
.I /etc/X11/__xconfigfile__
.I /etc/__xconfigfile__
.IR __projectroot__/etc/X11/__xconfigfile__. <hostname>
.I __projectroot__/etc/X11/__xconfigfile__-4
.I __projectroot__/etc/X11/__xconfigfile__\-4
.I __projectroot__/etc/X11/__xconfigfile__
.IR __projectroot__/lib/X11/__xconfigfile__. <hostname>
.I __projectroot__/lib/X11/__xconfigfile__-4
.I __projectroot__/lib/X11/__xconfigfile__\-4
.I __projectroot__/lib/X11/__xconfigfile__
.fi
.RE
.PP
where
.I <cmdline>
is a relative path (with no ".." components) specified with the
is a relative path (with no \(lq..\(rq components) specified with the
.B \-config
command line option,
.B $XORGCONFIG
is the relative path (with no ".." components) specified by that
is the relative path (with no \(lq..\(rq components) specified by that
environment variable, and
.I <hostname>
is the machine's hostname as reported by gethostname(3).
is the machine's hostname as reported by
.BR gethostname (__oslibmansuffix__).
.PP
When the __xservername__ server is started by the "root" user, the config file
When the __xservername__ server is started by the \(lqroot\(rq user, the config file
search locations are as follows:
.PP
.RS 4
......@@ -66,14 +68,14 @@ search locations are as follows:
.IB /etc/X11/ $XORGCONFIG
.IB __projectroot__/etc/X11/ $XORGCONFIG
.BI $HOME /__xconfigfile__
.I /etc/X11/__xconfigfile__-4
.I /etc/X11/__xconfigfile__\-4
.I /etc/X11/__xconfigfile__
.I /etc/__xconfigfile__
.IR __projectroot__/etc/X11/__xconfigfile__. <hostname>
.I __projectroot__/etc/X11/__xconfigfile__-4
.I __projectroot__/etc/X11/__xconfigfile__\-4
.I __projectroot__/etc/X11/__xconfigfile__
.IR __projectroot__/lib/X11/__xconfigfile__. <hostname>
.I __projectroot__/lib/X11/__xconfigfile__-4
.I __projectroot__/lib/X11/__xconfigfile__\-4
.I __projectroot__/lib/X11/__xconfigfile__
.fi
.RE
......@@ -90,13 +92,13 @@ environment variable (absolute or relative),
is the path specified by that environment variable (usually the home
directory), and
.I <hostname>
is the machine's hostname as reported by gethostname(3).
is the machine's hostname as reported by
.BR gethostname (__oslibmansuffix__).
.PP
The
.B __xconfigfile__
file is composed of a number of sections which may be present in any
order. Each section has
the form:
.I __xconfigfile__
file is composed of a number of sections which may be present in any order.
Each section has the form:
.PP
.RS 4
.nf
......@@ -121,13 +123,14 @@ The section names are:
.BR "Modes " "Video modes descriptions"
.BR "Screen " "Screen configuration"
.BR "ServerLayout " "Overall layout"
.BR "DRI " "DRI-specific configuration"
.BR "Vendor " "Vendor-specific configuration"
.BR "DRI " "DRI\-specific configuration"
.BR "Vendor " "Vendor\-specific configuration"
.fi
.RE
.PP
The following obsolete section names are still recognised for compatibility
purposes. In new config files, the
purposes.
In new config files, the
.B InputDevice
section should be used instead.
.PP
......@@ -144,35 +147,38 @@ section is no longer recognised.
.PP
The
.B ServerLayout
sections are at the highest level. They bind together the input and
output devices that will be used in a session. The input devices
are described in the
sections are at the highest level.
They bind together the input and output devices that will be used in a session.
The input devices are described in the
.B InputDevice
sections. Output devices usually consist of multiple independent
components (e.g., a graphics board and a monitor). These multiple
components are bound together in the
sections.
Output devices usually consist of multiple independent components (e.g.,
a graphics board and a monitor).
These multiple components are bound together in the
.B Screen
sections, and it is these that are referenced by the
.B ServerLayout
section. Each
section.
Each
.B Screen
section binds together a graphics board and a monitor. The graphics
boards are described in the
section binds together a graphics board and a monitor.
The graphics boards are described in the
.B Device
sections, and the monitors are described in the
.B Monitor
sections.
.PP
Config file keywords are case-insensitive, and "_" characters are
ignored. Most strings (including
Config file keywords are case\-insensitive, and \(lq_\(rq characters are
ignored.
Most strings (including
.B Option
names) are also case-insensitive, and insensitive to white space and
"_" characters.
\(lq_\(rq characters.
.PP
Each config file entry usually takes up a single line in the file.
They consist of a keyword, which is possibly followed by one or
more arguments, with the number and types of the arguments depending
on the keyword. The argument types are:
Each config file entry usually takes up a single line in the file. They
consist of a keyword, which is possibly followed by one or more arguments,
with the number and types of the arguments depending on the keyword.
The argument types are:
.PP
.RS 4
.nf
......@@ -182,17 +188,18 @@ on the keyword. The argument types are:
.fi
.RE
.PP
Note: hex integer values must be prefixed with "0x", and octal values
with "0".
Note: hex integer values must be prefixed with \(lq0x\(rq, and octal values
with \(lq0\(rq.
.PP
A special keyword called
.B Option
may be used to provide free-form data to various components of the server.
may be used to provide free\-form data to various components of the server.
The
.B Option
keyword takes either one or two string arguments. The first is the option
name, and the optional second argument is the option value. Some commonly
used option value types include:
keyword takes either one or two string arguments.
The first is the option name, and the optional second argument is the
option value.
Some commonly used option value types include:
.PP
.RS 4
.nf
......@@ -209,8 +216,8 @@ Note that
.B Option
values, not just strings, must be enclosed in quotes.
.PP
Boolean options may optionally have a value specified. When no value
is specified, the option's value is
Boolean options may optionally have a value specified.
When no value is specified, the option's value is
.BR TRUE .
The following boolean option values are recognised as
.BR TRUE :
......@@ -263,30 +270,35 @@ When the unit name is omitted, the correct units will be determined from
the value and the expectations of the appropriate range of the value.
It is recommended that the units always be specified when using frequency
option values to avoid any errors in determining the value.
.SH FILES SECTION
.SH "FILES SECTION"
The
.B Files
section is used to specify some path names required by the server.
Some of these paths can also be set from the command line (see Xserver(__appmansuffix__)
and __xservername__(__appmansuffix__)). The command line settings override the values specified
in the config file. The
Some of these paths can also be set from the command line (see
.BR Xserver (__appmansuffix__)
and
.BR __xservername__ (__appmansuffix__)).
The command line settings override the values specified in the config
file.
The
.B Files
section is optional, as are all of the entries that may appear in it.
.PP
The entries that can appear in this section are:
.TP 7
.BI "FontPath \*q" path \*q
sets the search path for fonts. This path is a comma separated list of
font path elements which the __xservername__ server searches for font databases.
sets the search path for fonts.
This path is a comma separated list of font path elements which the __xservername__
server searches for font databases.
Multiple
.B FontPath
entries may be specified, and they will be concatenated to build up the
fontpath used by the server. Font path elements may be either absolute
directory paths, or a font server identifier. Font server identifiers
have the form:
directory paths, or a font server identifier.
Font server identifiers have the form:
.PP
.RS 11
.IR <trans> / <hostname> : <port-number>
.IR <trans> / <hostname> : <port\-number>
.RE
.PP
.RS 7
......@@ -294,16 +306,16 @@ where
.I <trans>
is the transport type to use to connect to the font server (e.g.,
.B unix
for UNIX-domain sockets or
for UNIX\-domain sockets or
.B tcp
for a TCP/IP connection),
.I <hostname>
is the hostname of the machine running the font server, and
.I <port-number>
.I <port\-number>
is the port number that the font server is listening on (usually 7100).
.PP
When this entry is not specified in the config file, the server falls back
to the compiled-in default font path, which contains the following
to the compiled\-in default font path, which contains the following
font path elements:
.PP
.RS 4
......@@ -338,7 +350,7 @@ font path when the server starts up.
.BI "RGBPath \*q" path \*q
sets the path name for the RGB color database.
When this entry is not specified in the config file, the server falls back
to the compiled-in default RGB path, which is:
to the compiled\-in default RGB path, which is:
.PP
.RS 11
.I __projectroot__/share/X11/rgb
......@@ -350,9 +362,10 @@ is added to this path if the server was compiled to use text rather than
binary format RGB color databases.
.TP 7
.BI "ModulePath \*q" path \*q
sets the search path for loadable __xservername__ server modules. This path is
a comma separated list of directories which the __xservername__ server searches
for loadable modules loading in the order specified. Multiple
sets the search path for loadable __xservername__ server modules.
This path is a comma separated list of directories which the __xservername__ server
searches for loadable modules loading in the order specified.
Multiple
.B ModulePath
entries may be specified, and they will be concatenated to build the
module search path used by the server.
......@@ -360,8 +373,8 @@ module search path used by the server.
.ig
.TP 7
.BI "LogFile \*q" path \*q
sets the name of the __xservername__ server log file. The default log file name
is
sets the name of the __xservername__ server log file.
The default log file name is
.PP
.RS 11
.RI __logdir__/__xservername__. <n> .log
......@@ -372,15 +385,18 @@ where
.I <n>
is the display number for the __xservername__ server.
..
.SH SERVERFLAGS SECTION
.SH "SERVERFLAGS SECTION"
In addition to options specific to this section (described below), the
.B ServerFlags
section is used to specify some global
__xservername__ server options. All of the entries in this section are
__xservername__ server options.
All of the entries in this section are
.BR Options ,
although for compatibility purposes some of the old style entries are
still recognised. Those old style entries are not documented here, and
using them is discouraged. The
still recognised.
Those old style entries are not documented here, and using them is
discouraged.
The
.B ServerFlags
section is optional, as are the entries that may be specified in it.
.PP
......@@ -392,11 +408,12 @@ may be overridden by
.B Options
specified in the active
.B ServerLayout
section. Options with command line equivalents are overridden when their
command line equivalent is used. The options recognised by this section
are:
section.
Options with command line equivalents are overridden when their command
line equivalent is used.
The options recognised by this section are:
.TP 7
.BI "Option \*qDefaultServerLayout\*q \*q" layout-id \*q
.BI "Option \*qDefaultServerLayout\*q \*q" layout\-id \*q
This specifies the default
.B ServerLayout
section to use in the absence of the
......@@ -404,148 +421,185 @@ section to use in the absence of the
command line option.
.TP 7
.BI "Option \*qNoTrapSignals\*q \*q" boolean \*q
This prevents the __xservername__ server from trapping a range of unexpected
fatal signals and exiting cleanly. Instead, the __xservername__ server will die
and drop core where the fault occurred. The default behaviour is
for the __xservername__ server to exit cleanly, but still drop a core file. In
general you never want to use this option unless you are debugging
an __xservername__ server problem and know how to deal with the consequences.
This prevents the __xservername__ server from trapping a range of unexpected fatal
signals and exiting cleanly.
Instead, the __xservername__ server will die and drop core where the fault occurred.
The default behaviour is for the __xservername__ server to exit cleanly, but still drop a
core file.
In general you never want to use this option unless you are debugging an __xservername__
server problem and know how to deal with the consequences.
.TP 7
.BI "Option \*qDontVTSwitch\*q \*q" boolean \*q
This disallows the use of the
.BI Ctrl+Alt+F n
sequence (where
.RI F n
refers to one of the numbered function keys). That sequence is normally
used to switch to another \*qvirtual terminal\*q on operating systems
that have this feature. When this option is enabled, that key sequence has
no special meaning and is passed to clients. Default: off.
refers to one of the numbered function keys).
That sequence is normally used to switch to another \*qvirtual terminal\*q
on operating systems that have this feature.
When this option is enabled, that key sequence has no special meaning and
is passed to clients.
Default: off.
.TP 7
.BI "Option \*qDontZap\*q \*q" boolean \*q
This disallows the use of the
.B Ctrl+Alt+Backspace
sequence. That sequence is normally used to terminate the __xservername__ server.
When this option is enabled, that key sequence has no special meaning
and is passed to clients. Default: off.
sequence.
That sequence is normally used to terminate the __xservername__ server.
When this option is enabled, that key sequence has no special meaning and
is passed to clients.
Default: off.
.TP 7
.BI "Option \*qDontZoom\*q \*q" boolean \*q
This disallows the use of the
.B Ctrl+Alt+Keypad-Plus
.B Ctrl+Alt+Keypad\-Plus
and
.B Ctrl+Alt+Keypad-Minus
sequences. These sequences allows you to switch between video modes.
.B Ctrl+Alt+Keypad\-Minus
sequences.
These sequences allows you to switch between video modes.
When this option is enabled, those key sequences have no special meaning
and are passed to clients. Default: off.
and are passed to clients.
Default: off.
.TP 7
.BI "Option \*qDisableVidModeExtension\*q \*q" boolean \*q
This disables the parts of the VidMode extension used by the xvidtune client
that can be used to change the video modes. Default: the VidMode extension
is enabled.
that can be used to change the video modes.
Default: the VidMode extension is enabled.
.TP 7
.BI "Option \*qAllowNonLocalXvidtune\*q \*q" boolean \*q
This allows the xvidtune client (and other clients that use the VidMode
extension) to connect from another host. Default: off.
extension) to connect from another host.
Default: off.
.TP 7
.BI "Option \*qDisableModInDev\*q \*q" boolean \*q
This disables the parts of the __xservername__-Misc extension that can be used to
modify the input device settings dynamically. Default: that functionality
is enabled.
This disables the parts of the __xservername__\-Misc extension that can be used to
modify the input device settings dynamically.
Default: that functionality is enabled.
.TP 7
.BI "Option \*qAllowNonLocalModInDev\*q \*q" boolean \*q
This allows a client to connect from another host and change keyboard
and mouse settings in the running server. Default: off.
and mouse settings in the running server.
Default: off.
.TP 7
.BI "Option \*qAllowMouseOpenFail\*q \*q" boolean \*q
This allows the server to start up even if the mouse device can't be
opened/initialised. Default: false.
opened/initialised.
Default: false.
.TP 7
.BI "Option \*qVTInit\*q \*q" command \*q
Runs
.I command
after the VT used by the server has been opened.
The command string is passed to "/bin/sh -c", and is run with the
real user's id with stdin and stdout set to the VT. The purpose
of this option is to allow system dependent VT initialisation
commands to be run. This option should rarely be needed. Default: not set.
The command string is passed to \*q/bin/sh \-c\*q, and is run with the real
user's id with stdin and stdout set to the VT.
The purpose of this option is to allow system dependent VT initialisation
commands to be run.
This option should rarely be needed.
Default: not set.
.TP 7
.BI "Option \*qVTSysReq\*q \*q" boolean \*q
enables the SYSV-style VT switch sequence for non-SYSV systems
which support VT switching. This sequence is
.B Alt-SysRq
followed
by a function key
enables the SYSV\-style VT switch sequence for non\-SYSV systems
which support VT switching.
This sequence is
.B Alt\-SysRq
followed by a function key
.RB ( Fn ).
This prevents the __xservername__ server trapping the
keys used for the default VT switch sequence, which means that clients can
access them. Default: off.
access them.
Default: off.
.TP 7
.BI "Option \*qXkbDisable\*q \*q" boolean \*q
disable/enable the XKEYBOARD extension. The \-kb command line
option overrides this config file option. Default: XKB is enabled.
disable/enable the XKEYBOARD extension.
The \-kb command line option overrides this config file option.
Default: XKB is enabled.
.\" The following four options are "undocumented".
.ig
.TP 7
.BI "Option \*qPciProbe1\*q"
Use PCI probe method 1. Default: set.
Use PCI probe method 1.
Default: set.
.TP 7
.BI "Option \*qPciProbe2\*q"
Use PCI probe method 2. Default: not set.
Use PCI probe method 2.
Default: not set.
.TP 7
.BI "Option \*qPciForceConfig1\*q"
Force the use PCI config type 1. Default: not set.
Force the use PCI config type 1.
Default: not set.
.TP 7
.BI "Option \*qPciForceConfig2\*q"
Force the use PCI config type 2. Default: not set.
Force the use PCI config type 2.
Default: not set.
..
.TP 7
.BI "Option \*qBlankTime\*q \*q" time \*q
sets the inactivity timeout for the blanking phase of the screensaver.
sets the inactivity timeout for the
.B blank
phase of the screensaver.
.I time
is in minutes. This is equivalent to the __xservername__ server's `-s' flag,
and the value can be changed at run-time with xset(__appmansuffix__). Default: 10
minutes.
is in minutes.
This is equivalent to the __xservername__ server's
.B \-s
flag, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
Default: 10 minutes.
.TP 7
.BI "Option \*qStandbyTime\*q \*q" time \*q
sets the inactivity timeout for the "standby" phase of DPMS mode.
sets the inactivity timeout for the
.B standby
phase of DPMS mode.
.I time
is in minutes, and the value can be changed at run-time with xset(__appmansuffix__).
Default: 20 minutes. This is only suitable for VESA DPMS compatible
monitors, and may not be supported by all video drivers. It is only
enabled for screens that have the
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
Default: 20 minutes.
This is only suitable for VESA DPMS compatible monitors, and may not be
supported by all video drivers.
It is only enabled for screens that have the
.B \*qDPMS\*q
option set (see the MONITOR section below).
.TP 7
.BI "Option \*qSuspendTime\*q \*q" time \*q
sets the inactivity timeout for the "suspend" phase of DPMS mode.
sets the inactivity timeout for the
.B suspend
phase of DPMS mode.
.I time
is in minutes, and the value can be changed at run-time with xset(__appmansuffix__).
Default: 30 minutes. This is only suitable for VESA DPMS compatible
monitors, and may not be supported by all video drivers. It is only
enabled for screens that have the
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
Default: 30 minutes.
This is only suitable for VESA DPMS compatible monitors, and may not be
supported by all video drivers.
It is only enabled for screens that have the
.B \*qDPMS\*q
option set (see the MONITOR section below).
.TP 7
.BI "Option \*qOffTime\*q \*q" time \*q
sets the inactivity timeout for the "off" phase of DPMS mode.
sets the inactivity timeout for the
.B off
phase of DPMS mode.
.I time
is in minutes, and the value can be changed at run-time with xset(__appmansuffix__).
Default: 40 minutes. This is only suitable for VESA DPMS compatible
monitors, and may not be supported by all video drivers. It is only
enabled for screens that have the
is in minutes, and the value can be changed at run\-time with
.BR xset(__appmansuffix__).
Default: 40 minutes.
This is only suitable for VESA DPMS compatible monitors, and may not be
supported by all video drivers.
It is only enabled for screens that have the
.B \*qDPMS\*q
option set (see the MONITOR section below).
.TP 7
.BI "Option \*qPixmap\*q \*q" bpp \*q
This sets the pixmap format to use for depth 24. Allowed values for
This sets the pixmap format to use for depth 24.
Allowed values for
.I bpp
are 24 and 32. Default: 32 unless driver constraints don't allow this
(which is rare). Note: some clients don't behave well when this value
is set to 24.
are 24 and 32.
Default: 32 unless driver constraints don't allow this (which is rare).
Note: some clients don't behave well when this value is set to 24.
.TP 7
.BI "Option \*qPC98\*q \*q" boolean \*q
Specify that the machine is a Japanese PC-98 machine. This should not
be enabled for anything other than the Japanese-specific PC-98
architecture. Default: auto-detected.
Specify that the machine is a Japanese PC\-98 machine.
This should not be enabled for anything other than the Japanese\-specific
PC\-98 architecture.
Default: auto\-detected.
.\" Doubt this should be documented.
.ig
.TP 7
......@@ -555,48 +609,54 @@ Default: 0.
..
.TP 7
.BI "Option \*qNoPM\*q \*q" boolean \*q
Disables something to do with power management events. Default: PM
enabled on platforms that support it.
Disables something to do with power management events.
Default: PM enabled on platforms that support it.
.TP 7
.BI "Option \*qXinerama\*q \*q" boolean \*q
enable or disable XINERAMA extension. Default is disabled.
enable or disable XINERAMA extension.
Default is disabled.
.TP 7
.BI "Option \*qAllowDeactivateGrabs\*q \*q" boolean \*q
This option enables the use of the
.B Ctrl+Alt+Keypad-Divide
key sequence to deactivate any active keyboard and mouse grabs. Default:
off.
.B Ctrl+Alt+Keypad\-Divide
key sequence to deactivate any active keyboard and mouse grabs.
Default: off.
.TP 7
.BI "Option \*qAllowClosedownGrabs\*q \*q" boolean \*q
This option enables the use of the
.B Ctrl+Alt+Keypad-Multiply
key sequence to kill clients with an active keyboard or mouse grab as
well as killing any application that may have locked the server, normally
using the XGrabServer(__libmansuffix__) Xlib function. Default: off.
.B Ctrl+Alt+Keypad\-Multiply
key sequence to kill clients with an active keyboard or mouse grab as well
as killing any application that may have locked the server, normally using
the
.BR XGrabServer(__libmansuffix__)
Xlib function.
Default: off.
.br
Note that the options
.BI AllowDeactivateGrabs
.B AllowDeactivateGrabs
and
.BI AllowClosedownGrabs
.B AllowClosedownGrabs
will allow users to remove the grab used by screen saver/locker programs.
An API was written to such cases. If you enable this option, make sure
your screen saver/locker is updated.
An API was written to such cases.
If you enable this option, make sure your screen saver/locker is updated.
Default: off.
.TP 7
.BI "Option \*qHandleSpecialKeys\*q \*q" when \*q
This option controls when the server uses the builtin handler to process
special key combinations (such as
.BR Ctrl+Alt+Backspace ).
Normally the XKEYBOARD extension keymaps will provide mappings for each
of the special key combinations, so the builtin handler is not needed
unless the XKEYBOARD extension is disabled. The value of
Normally the XKEYBOARD extension keymaps will provide mappings for each of
the special key combinations, so the builtin handler is not needed unless
the XKEYBOARD extension is disabled.
The value of
.I when