| Xsession(5) | File Formats Manual | Xsession(5) |
Xsession - initialize X session
Xsession [ session-type ]
/etc/X11/Xsession is a Bourne shell (sh(1)) script which is run when an X Window System session is begun by startx(1) or a display manager such as xdm(1). (Some display managers only invoke Xsession when specifically directed to so by the user; see the documentation for your display manager to find out more.) Administrators unfamiliar with the Bourne shell will likely find the Xsession.options(5) configuration file easier to deal with than Xsession itself.
Xsession is not intended to be invoked directly by the user; to be effective it needs to run in a special environment associated with X server initialization. startx, xdm, xinit(1), and other similar programs handle this.
By default on a Debian system, Xsession is used by both common methods of starting the X Window System, xdm (or another X display manager) and startx. To change this for xdm, edit the ‘DisplayManager*session’ resource in the /etc/X11/xdm/xdm-config file — for other display managers, consult their documentation. To stop startx from using Xsession by default, replace the contents of the /etc/X11/xinit/xinitrc file.
The Xsession script is quite flexible, and extensive customization of the X startup procedure is possible without modifying the script itself. See “CUSTOMIZING THE STARTUP PROCEDURE” below.
Xsession may optionally be passed a single argument indicating the type of X session to be started. It is up to the display manager to set the argument. To pass Xsession an argument from startx or xinit, /etc/X11/Xsession (or /etc/X11/xinit/xinitrc) must be called explicitly with a path, as in startx /etc/X11/Xsession failsafe. By default, three different arguments are supported:
Initially, Xsession performs some housekeeping. It declares a set of built-in functions (see “BUILT-IN SHELL FUNCTIONS” below) and variables, then attempts to create a log file for the X session, or append to an existing one. Historically this is called an ‘error’ file, but it catches all sorts of diagnostic output from various X clients run in the user's session, not just error messages. If it is impossible to write to an error file, the script (and thus the X session) aborts. For convenience, once the error file is successfully opened, Xsession reports the fact that the session has started, the invoking username, and the date to the error file. This makes it easier to discern which X session produced a particular line of output in the file.
Xsession next confirms that its script directory, Xsession.d, exists. If it does not, the script aborts. After the script directory is confirmed to be present, Xsession uses run-parts(1) to identify files in that directory that should be sourced (executed) in the shell's environment. Only files named in a certain way are sourced; see the run-parts manual page for a description of valid characters in the filename. (This restriction enables the administrator to move experimental or problematic files out of the way of the script but keep them in an obvious place, for instance by renaming them with ‘.old’ or ‘.broken’ appended to the filename.)
Five shell script portions are supplied by default to handle the details of the session startup procedure.
Of course, any of the existing files can be edited in place.
Because the order in which the various scripts in /etc/X11/Xsession.d are executed is important, files to be added to this directory should have a well-formed name. The following format is recommended:
* a two-digit number denoting sequence;
* the name of the package providing the script (or ‘custom’ for locally-created scripts);
* an underscore;
* a description of the script's basic function, using only characters allowed by run-parts.
Here is an example of how one might write a script, named 40custom_load-xmodmap, to invoke xmodmap(1):
SYSMODMAP="/etc/X11/Xmodmap" USRMODMAP="$HOME/.Xmodmap"
if [ -x /usr/bin/X11/xmodmap ]; then
if [ -f "$SYSMODMAP" ]; then
xmodmap "$SYSMODMAP"
fi fi
if [ -x /usr/bin/X11/xmodmap ]; then
if [ -f "$USRMODMAP" ]; then
xmodmap "$USRMODMAP"
fi fi
Those writing scripts for Xsession to execute should avail themselves of its built-in shell functions, described below.
message is used for communicating with the user. It is a wrapper for the echo(1) command and relies upon echo for its argument processing. This function may be given an arbitrarily long message string, which is formatted to the user's terminal width (breaking lines at whitespace) and sent to standard error. If the DISPLAY environment variable is set and the xmessage(1) program is available, xmessage is also used to display the message.
message_nonl is used for communicating with the user when a trailing newline is undesirable; it omits a trailing newline from the message text. It otherwise works as message.
errormsg is used for indicating an error condition and aborting the script. It works as message, above, except that after displaying the message, it will exit Xsession with status 1.
The following environment variables affect the execution of Xsession:
Stephen Early, Mark Eichin, and Branden Robinson developed Debian's X session handling scripts. Branden Robinson wrote this manual page.
Xsession.options(5), X(7), run-parts(1), ssh-agent(1), startx(1), tempfile(1), xdm(1), xmessage(1), xmodmap(1), xrdb(1), sh(1)
| 2004-11-04 | Debian Project |