NAME

Xconfig - Configuration File for XFree86

DESCRIPTION

XFree86 uses a configuration file called Xconfig for its initial setup.  If this file is not specified from the command line with the −xconfig flag then the methods described here are used to find the file.  If the environment variable XCONFIG is set to a pathname, this is used as the name of the configuration file.  If XCONFIG is set, but is not a pathname (i.e., doesn’t contain a ‘/’) it is appended to Xconfig.  The configuration file is then searched for in the following places:

$HOME/Xconfig
/etc/Xconfig
/usr/X386/lib/X11/Xconfig.hostname
/usr/X386/lib/X11/Xconfig

This file is composed of the following sections:

General Server Parameters
Keyboard Configuration
Mouse Configuration
Video Mode Setup
Table of Known Video Modes

The GENERAL SERVER PARAMETERS section lets you adjust some generic server parameter which seldom change for a given site.  (The fontpath and rgbpath parameters can also be set from the command line, see Xserver(1).):

fontpath "path"
sets the search path for fonts.  This path is a comma separated list of directories which the sample server searches for font databases.  Multiple fontpath entries may be specified, and they will be concatenated to build up the fontpath used by the server.  Note that a new feature of X11R5 is the ability of the X server to request fonts from a font server.  One specifies a font server by placing a "tcp/<hostname>:<tcp_port_number>" into the fontpath.  In the above example, the fontpath "/usr/X386/lib/X11/fonts/misc/,tcp/zok:7000" tells XFree86 to first try to locate the font in the local directory /usr/X386/lib/X11/fonts/misc.  If that fails, then request the font from the font server running on machine zok listening for connections on TCP port number 7000. 

rgbpath "path"
sets the name of RGB color database.

notrapsignals
prevents the server from trapping a range of unexpected fatal signals and exiting cleanly.  Instead, the server will die and drop core where the fault occurred.  The default behaviour is for the server exit cleanly, but still drop a core file. In general you never want to use this option unless you are debugging a server problem.

The KEYBOARD CONFIGURATION section starts with a keyword describing which kind  of driver should be used:  keyboard (the normal device) or xqueue (the event-queue driver in SVR3 and SVR4).  Following this keyword the following options can be specified:

autorepeat delay rate
changes the behavior of the autorepeat of the keyboard.  This does not work on all platforms.

dontzap
disallows the use of the Ctrl+Alt+Backspace sequence.  This sequence allows you to terminate the server. 

servernumlock
forces the server to handle the numlock key internally.  The server sends a different set of keycodes for the numpad when the numlock key is active. This enables applications to make use of the numpad.

leftalt mapping
rightalt mapping
altgr mapping
scrolllock mapping
rightctl mapping

Allows a default mapping to be set for the above keys (note that altgr is a synonym for rightalt).  The values that may be specified for mapping are:

meta
compose
modeshift
modelock
scrolllock
control

The default mapping when none of these options are specified is:

leftalt     meta
rightalt    meta
scrolllock  compose
rightctl    control

Refer to the XFree86kbd(1) manual page for more information. 

xleds led ... 
makes led available for clients instead of using the traditional function (Scroll Lock, Caps Lock & Num Lock)

vtinit "command"
Runs 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.  One example is a command to disable the 2-key VT switching sequence which is the default on some systems. 

Similar to above, the MOUSE CONFIGURATION section starts with a special keyword, but here we must select the type of mouse (i.e. its protocol) that is connected to the computer.  (When using the xqueue driver this section should be deleted (except the emulate3buttons keyword), since mouse I/O is handled by the xqueue driver.)  The mouse types available are:

busmouse
logitech
microsoft
mmseries
mouseman
mousesystems
ps/2
mmhittab

Under SCO another mouse type (osmouse) is available.  This mouse type uses the SCO event drivers to access the mouse.  This type should be used for bus and ps/2 mice but it may also be used for serial mice.  In order to use this type you must first configure your OS appropriately with "mkdev mouse". See the manual page ("man mouse") for more information reguarding mouse configuration under SCO.  If the osmouse driver incorrectly reports the number of buttons available for the currently configured mouse then it may be followed by a number of buttons (ie., osmouse 4 for a four button mouse). 

(One should specify busmouse for the Logitech bus mouse.)  Immediately following the mouse type should be the mouse device in quotations (e.g. "/dev/tty00").  The following options can be specified after this keyword:

baudrate rate
sets the baudrate of the serial mouse to rate. For mice that allow dynamic speed adjustments (like logitech) the baudrate is changed in the mouse.  Otherwise the rate is simply set on the computer’s side to allow mice with non-standard rates (the standard rate is 1200). 

emulate3buttons
enables the emulation of the third mouse button for mice which only have two physical buttons.  The third button is emulated by pressing both buttons simultaneously.

chordmiddle
handles mice which send left+right events when the middle button is used.

samplerate rate
sets the number of motion/button-events the mouse sends per second. This is currently only supported for logitech mice.

cleardtr This options clears the DTR line on the serial port used by the mouse.  This option is only valid for a mouse using the mousesystems protocol.  Some dual-protocol mice require DTR to be cleared to operate in mousesystems mode. 

The GRAPHICS DRIVER SETUP section depends on the actually used server. Here only the general features are explained, for more detail see the server specific manpages.  For the SVGA colour server the GRAPHICS DRIVER SETUP section starts with the keyword vga256.  The section for the monochrome server starts with the keyword vga2, the 4-bit server uses the keyword vga16, and the section for the mono hga driver starts with the keyword hga2, and the section for the bdm driver starts with the keyword bdm2. The accelerated servers like the S3 server, the Mach8 or the Mach32 server, use the keyword accel.  For servers with multiple screens supported, only those with entries will be enabled.  After this keyword a variety of options may be specified (most are not relevant to the hga2 driver because it only supports a single resolution):

staticgray,grayscale,staticcolor,pseudocolor,truecolor,directcolor
sets the visual class for the root window of the screen.  Note that the monochrome server only supports a staticgray visual, and the 16 colour VGA server only supports a pseudocolor visual. 

chipset "name"
specifies a chipset so the correct driver can be used or specifies a special driver to be used with the detected chipset. Details and valid values are given in the server specific manpages.

clocks clock ... 
specifies the dotclocks that are on your graphics board.  The clocks are in MHz, and may be specified as a floating point number.  The value is stored internally to the nearest kHz.  The ordering of the clocks is important.  It must match the order in which they are selected on the graphics board.  Multiple clocks lines may be specified.  For programmable clock chips the name of the clock chip is given.  Possible values include "icd2061a" and "icd2061a_slow".  These are currently only supported by the S3 server. 

clockprog "command" [textclock]
Runs command to set the clock on the graphics board instead of using the internal code.  The command string must consist of the full pathname (and no flags).  When using this option, a clocks option is required to specify which clock values are to be made available to the server (up to 32 clocks may be specified).  The optional textclock value is used to tell the server that command must be run to restore the textmode clock at server exit (or when VT switching).  textclock must match one of the values in the clocks line.  This parameter is required when the clock used for text mode is a programmable clock. 
 
The command is run with the real user’s id with stdin and stdout set to the graphics console device.  Two arguments are passed to the command. The first is the clock frequency in MHz as a floating point number and the second is the index of the clock in the clocks line.  The command should return an exit status of 0 when successful, and something in the range 1−254 otherwise. 
 
The command is run when the initial graphics mode is set and when changing screen resolution with the hot-key sequences.  If the program fails at initialisation the server exits.  If it fails during a mode switch, the mode switch is aborted but the server keeps running.  It is assumed that if the command fails the clock has not been changed.

screenno scrnum
overrides the default screen numbering on a multi-display server.  The default numbering is determined by the ordering of the screen sections in Xconfig.  To override this, all relevant screens must have this option specified.  This is the only option applicable the the hga2 screen. 

modes "mode" ... 
selects the display modes for this screen.  The first one in the list will be the default display mode for startup.  Internally this list is converted into a circular list.  With Ctrl+Alt+Keypad-Plus and Ctrl+Alt+Keypad-Minus the current display mode may be changed, and the next (upward/downward) entry in the list will be used. 

option "optionstring"
allows the user to select certain options provided by the drivers. The supported values are given in the server specific manpages.

videoram mem
specifies the amount of videoram that is installed on the graphics board. This is measured in kBytes.

biosbase baseaddress
specifies the base address of the video BIOS for the VGA card.  This address is normally at 0xC0000, which is the default the server will use.  Some systems, particularly those with on-board VGA hardware, have the BIOS located at an alternate address, usually 0xE0000.  If your video BIOS is at an address other than 0xC0000, you must specify the base address in the Xconfig file.  Note that the server only uses the BIOS when searching for information during the probe phase.

viewport x0 y0
sets the upper left corner of the initial display.  If the virtual resolution is larger than what is physically displayed, then the initial display will be centered if viewport is not specified. 

virtual xdim ydim
sets the virtual resolution. For example one might use a display with 800x600, but a virtual resolution of 1152x900.  xdim must be a multiple of either 8 or 16 for the colour server (depending on the chipset), and a multiple of 32 for the mono server.  The specified valued will be rounded down if this is not the case.  If the mouse touches the borders of the display the image scrolls accordingly. This is called panning. 

Note that XFree86 has some internal capabilities to determine what hardware it is running on. Thus normally the keywords chipset, clocks, and videoram don’t have to be specified.  But there may be occasions when this autodetection mechanism fails, (for example, too high of load on the machine when you start the server).  For cases like this, one should first run XFree86 on an unloaded machine, look at the results of the autodetection (that are printed out during server startup) and then explicitly specify these parameters in the configuration file.  It is recommended that all parameters, especially Clock values, be specified in the Xconfig file.

The last section is the TABLE OF VIDEO MODES which starts with the keyword modedb.  A list of possible mode-records follows this keyword.  For every mode string in the previously specified modes line, the server scans the list of mode-records looking for a matching modename.  When a match occurs, then the dotclock value is compared to those found on the graphics board.  If the dotclock value matches, then the rest of the values in the mode-record will be used for that display mode.  If there is more than one matching mode-record (for a given modename and dotclock), then the last one matched will be used.  A mode-record consists of seven parts (the first four are mandatory, while the last three are optional):

modename
is the string that identifies this mode. If one is not specified, then the modename string of the last valid mode-record is used. 

dotclock is the dotclock this mode uses. This is the basic timer for all video signals. 

hdisp, hsyncstart, hsyncend, htotal
is the horizontal timing

vdisp, vsyncstart, vsyncend, vtotal
is the vertical timing

interlace
sets interlace display mode.

+hsync, -hsync
selects polarity of HSYNC signal

+vsync, -vsync
selects polarity of VSYNC signal

For details on how to build your own video modes please refer to the tutorial written by Eric Raymond. 

A sample config file might look like this:

RGBPath         "/usr/X386/lib/X11/rgb"
FontPath        "/usr/X386/lib/X11/fonts/misc/,tcp/zok:7000"
 Keyboard
  AutoRepeat 500 5
  Xleds      1 2 3
  ServerNumLock
  DontZap
 Logitech"/dev/tty00"
  BaudRate9600
  SampleRate150
  Emulate3Buttons
 vga256
  Chipset       "et4000"
  Option        "legend"
  Clocks        25 28 36 62
  Virtual       1152 900
  ViewPort      0 0
  Modes         "1024x768" "640x480"
 ModeDB
 "640x480"   25     640  672  768  800    480  490  492  525
             28     640  672  768  800    480  490  492  525
 "1024x768"  62    1024 1092 1220 1344    768  786  791  810

FILES

$HOME/Xconfig
/etc/Xconfig
/usr/X386/lib/X11/Xconfig.hostname
/usr/X386/lib/X11/Xconfig
/usr/X386/lib/X11/etc/README.Config

SEE ALSO

X(1), Xserver(1), XFree86(1), XFree86kbd(1), XF86_SVGA(1), XF86_VGA16(1), XF86_Mono(1), XF86_S3(1), XF86_8514(1), XF86_Mach8(1), XF86_Mach32(1)

AUTHORS

Refer to the XFree86(1) manual page.