619 lines
15 KiB
HTML
619 lines
15 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Xsession</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Xsession</H1>
|
|
Section: File Formats (5)<BR>Updated: 2004-11-04<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Xsession - initialize X session
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
Xsession [
|
|
<I>session-type</I>
|
|
|
|
]
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<I>/etc/X11/Xsession</I>
|
|
|
|
is a Bourne shell
|
|
(<B><A HREF="/cgi-bin/man/man2html?1+sh">sh</A></B>(1))
|
|
|
|
script which is run when an X Window System
|
|
session is begun by
|
|
<B><A HREF="/cgi-bin/man/man2html?1+startx">startx</A></B>(1)
|
|
|
|
or a display manager such as
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xdm">xdm</A></B>(1).
|
|
|
|
(Some display managers only invoke
|
|
<I>Xsession</I>
|
|
|
|
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
|
|
<B><A HREF="/cgi-bin/man/man2html?5+Xsession.options">Xsession.options</A></B>(5)
|
|
|
|
configuration file easier to deal with than
|
|
<I>Xsession</I>
|
|
|
|
itself.
|
|
<P>
|
|
|
|
<I>Xsession</I>
|
|
|
|
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.
|
|
<B>startx</B>,
|
|
|
|
<B>xdm</B>,
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xinit">xinit</A></B>(1),
|
|
|
|
and other similar programs handle this.
|
|
<P>
|
|
|
|
By default on a Debian system,
|
|
<I>Xsession</I>
|
|
|
|
is used by both common methods of starting the X Window System,
|
|
<B>xdm</B>
|
|
|
|
(or another X display manager) and
|
|
<B>startx</B>.
|
|
|
|
To change this for
|
|
<B>xdm,</B>
|
|
|
|
edit the 'DisplayManager*session' resource in the
|
|
<I>/etc/X11/xdm/xdm-config</I>
|
|
|
|
file --- for other display managers, consult their documentation.
|
|
To stop
|
|
<B>startx</B>
|
|
|
|
from using
|
|
<I>Xsession</I>
|
|
|
|
by default, replace the contents of the
|
|
<I>/etc/X11/xinit/xinitrc</I>
|
|
|
|
file.
|
|
<P>
|
|
|
|
The
|
|
<I>Xsession</I>
|
|
|
|
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.
|
|
<A NAME="lbAE"> </A>
|
|
<H3>SESSION TYPES</H3>
|
|
|
|
<I>Xsession</I>
|
|
|
|
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
|
|
<I>Xsession</I>
|
|
|
|
an argument from
|
|
<B>startx</B>
|
|
|
|
or
|
|
<B>xinit</B>,
|
|
|
|
<I>/etc/X11/Xsession</I>
|
|
|
|
(or
|
|
<I>/etc/X11/xinit/xinitrc</I>)
|
|
|
|
must be called explicitly with a path, as in
|
|
<B>startx /etc/X11/Xsession</B>
|
|
|
|
<B>failsafe</B>.
|
|
|
|
By default, three different arguments are supported:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>failsafe</B>
|
|
|
|
<DD>
|
|
invokes a session consisting solely of an
|
|
<B><A HREF="/cgi-bin/man/man2html?1+x-terminal-emulator">x-terminal-emulator</A></B>(1)
|
|
|
|
(no window manager is launched).
|
|
If the
|
|
<B>x-terminal-emulator program cannot</B>
|
|
|
|
be found, the session exits.
|
|
The 'failsafe' argument is ignored if there is no
|
|
'allow-failsafe' line in
|
|
<I>Xsession.options</I>.
|
|
|
|
<DT id="2"><B>default</B>
|
|
|
|
<DD>
|
|
produces the same behavior as if no session type argument had been given at
|
|
all.
|
|
<DT id="3"><I>program</I>
|
|
|
|
<DD>
|
|
starts
|
|
<I>program</I>
|
|
|
|
if it can be found in the $PATH.
|
|
This is usually a session manager or a very featureful window manager.
|
|
If
|
|
<I>program</I>
|
|
|
|
is not found, the
|
|
<I>Xsession</I>
|
|
|
|
script proceeds with its default behavior.
|
|
This argument is ignored if there is no 'allow-user-xsession' line
|
|
in
|
|
<I>Xsession.options</I>.
|
|
|
|
(If the administrator does not want users writing their own
|
|
<I>.xsession</I>
|
|
|
|
files, it makes little sense to permit them to specify the names of
|
|
arbitrary programs to run.)
|
|
Note that the restriction may be easy to bypass, e.g. by using a
|
|
<I>.gnomerc</I>
|
|
|
|
file instead.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H3>DEFAULT STARTUP PROCEDURE</H3>
|
|
|
|
Initially,
|
|
<I>Xsession</I>
|
|
|
|
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,
|
|
<I>Xsession</I>
|
|
|
|
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.
|
|
<P>
|
|
|
|
<I>Xsession</I>
|
|
|
|
next confirms that its script directory,
|
|
<I>Xsession.d</I>,
|
|
|
|
exists.
|
|
If it does not, the script aborts.
|
|
After the script directory is confirmed to be present,
|
|
<I>Xsession</I>
|
|
|
|
uses
|
|
<B><A HREF="/cgi-bin/man/man2html?1+run-parts">run-parts</A></B>(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
|
|
<B>run-parts</B>
|
|
|
|
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.)
|
|
<A NAME="lbAG"> </A>
|
|
<H3>SUPPLIED SCRIPTS</H3>
|
|
|
|
Five shell script portions are supplied by default to handle the details of
|
|
the session startup procedure.
|
|
<DL COMPACT>
|
|
<DT id="4"><I>/etc/X11/Xsession.d/20x11-common_process-args</I>
|
|
|
|
<DD>
|
|
Arguments are processed as described in "SESSION TYPES" above.
|
|
The startup program, if one is identified at this point, is merely stored
|
|
for later reference, and not immediately executed.
|
|
<DT id="5"><I>/etc/X11/Xsession.d/30x11-common_xresources</I>
|
|
|
|
<DD>
|
|
X resources are merged.
|
|
<B>run-parts</B>
|
|
|
|
is again used, this time to identify files in the
|
|
<I>/etc/X11/Xresources</I>
|
|
|
|
directory that should be processed with 'xrdb -merge'.
|
|
Next, if the line 'allow-user-resources' is present in
|
|
<I>Xsession.options</I>,
|
|
|
|
the user's
|
|
<I>$HOME/.Xresources</I>
|
|
|
|
file is merged in the same way.
|
|
<DT id="6"><I>/etc/X11/Xsession.d/35x11-common_xhost-local</I>
|
|
|
|
<DD>
|
|
Give access to the X server to the same user on the local host.
|
|
If the
|
|
<I>xhost</I>
|
|
|
|
command is available, it will use it to allow any process of the same
|
|
user running on the local host to access the X server.
|
|
<DT id="7"><I>/etc/X11/Xsession.d/40x11-common_xsessionrc</I>
|
|
|
|
<DD>
|
|
Source global environment variables.
|
|
This script will source anything in
|
|
<I>$HOME/.xsessionrc</I>
|
|
|
|
if the file is present. This allows the user to set global environment
|
|
variables for their X session, such as locale information.
|
|
<DT id="8"><I>/etc/X11/Xsession.d/50x11-common_determine-startup</I>
|
|
|
|
<DD>
|
|
Determine startup program.
|
|
The X client to launch as the controlling process (the one that, upon
|
|
exiting, causes the X server to exit as well) is determined next.
|
|
If a program or failsafe argument was given and is allowed (see above), it
|
|
is used as the controlling process.
|
|
Otherwise, if the line 'allow-user-xsession' is present in
|
|
<I>Xsession.options</I>,
|
|
|
|
a user-specified session program or script is used.
|
|
In the latter case, two historically popular names for user X session
|
|
scripts are searched for:
|
|
<I>$HOME/.xsession</I>
|
|
|
|
and
|
|
<I>$HOME/.Xsession</I>
|
|
|
|
(note the difference in case).
|
|
The first one found is used.
|
|
If the script is not executable, it is marked to be executed with the
|
|
Bourne shell interpreter,
|
|
<B>sh</B>.
|
|
|
|
Finally, if none of the above succeeds, the following programs are searched
|
|
for:
|
|
<I>/usr/bin/x-session-manager</I>,
|
|
|
|
<I>/usr/bin/x-window-manager</I>,
|
|
|
|
and
|
|
<I>/usr/bin/x-terminal-emulator</I>.
|
|
|
|
The first one found is used.
|
|
If none are found,
|
|
<I>Xsession</I>
|
|
|
|
aborts with an error.
|
|
<DT id="9"><I>/etc/X11/Xsession.d/90x11-common_ssh-agent</I>
|
|
|
|
<DD>
|
|
Start
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ssh-agent">ssh-agent</A></B>(1),
|
|
|
|
if needed.
|
|
If the line 'use-ssh-agent' is present in
|
|
<I>Xsession.options</I>,
|
|
|
|
and no SSH agent process appears to be running already,
|
|
<B>ssh-agent</B>
|
|
|
|
is marked to be used to execute the startup program determined previously.
|
|
<B>Note:</B>
|
|
|
|
this functionality may move to the ssh package in the future.
|
|
<DT id="10"><I>/etc/X11/Xsession.d/99x11-common_start</I>
|
|
|
|
<DD>
|
|
Start the X session.
|
|
The startup program is executed, inside a Bourne shell if it is not
|
|
executable, and inside an ssh-agent if necessary.
|
|
The shell's
|
|
<B>exec</B>
|
|
|
|
command is used to spare a slot in the process table.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H3>CUSTOMIZING THE STARTUP PROCEDURE</H3>
|
|
|
|
Of course, any of the existing files can be edited in place.
|
|
<P>
|
|
|
|
Because the order in which the various scripts in
|
|
<I>/etc/X11/Xsession.d</I>
|
|
|
|
are executed is important, files to be added to this directory should
|
|
have a well-formed name.
|
|
The following format is recommended:
|
|
<P>
|
|
|
|
* a two-digit number denoting sequence;
|
|
<P>
|
|
|
|
* the name of the package providing the script (or 'custom' for
|
|
locally-created scripts);
|
|
<P>
|
|
|
|
* an underscore;
|
|
<P>
|
|
|
|
* a description of the script's basic function, using only characters allowed
|
|
by
|
|
<B>run-parts</B>.
|
|
|
|
<P>
|
|
|
|
Here is an example of how one might write a script, named
|
|
<I>40custom_load-xmodmap</I>,
|
|
|
|
to invoke
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xmodmap">xmodmap</A></B>(1):
|
|
|
|
<P>
|
|
|
|
<PRE>
|
|
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
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
Those writing scripts for
|
|
<I>Xsession</I>
|
|
|
|
to execute should avail themselves of its built-in shell functions,
|
|
described below.
|
|
<A NAME="lbAI"> </A>
|
|
<H3>BUILT-IN SHELL FUNCTIONS</H3>
|
|
|
|
<B>message</B>
|
|
|
|
is used for communicating with the user.
|
|
It is a wrapper for the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+echo">echo</A></B>(1)
|
|
|
|
command and relies upon
|
|
<B>echo</B>
|
|
|
|
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
|
|
<I>DISPLAY</I>
|
|
|
|
environment variable is set and the
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xmessage">xmessage</A></B>(1)
|
|
|
|
program is available,
|
|
<B>xmessage</B>
|
|
|
|
is also used to display the message.
|
|
<P>
|
|
|
|
<B>message_nonl</B>
|
|
|
|
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
|
|
<B>message</B>.
|
|
|
|
<P>
|
|
|
|
<B>errormsg</B>
|
|
|
|
is used for indicating an error condition and aborting the script.
|
|
It works as
|
|
<B>message</B>,
|
|
|
|
above, except that after displaying the message, it will exit
|
|
<I>Xsession</I>
|
|
|
|
with status 1.
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>ENVIRONMENT</H2>
|
|
|
|
The following environment variables affect the execution of
|
|
<I>Xsession</I>:
|
|
|
|
<DL COMPACT>
|
|
<DT id="11"><B>HOME</B>
|
|
|
|
<DD>
|
|
specifies the user's home directory; various files are searched for here.
|
|
<DT id="12"><B>TMPDIR</B>
|
|
|
|
<DD>
|
|
names a default directory for temporary files; if the standard X session
|
|
error file cannot be opened, this variable is used to locate a place for
|
|
one.
|
|
<DT id="13"><B>COLUMNS</B>
|
|
|
|
<DD>
|
|
indicates the width of terminal device in character cells.
|
|
This value is used for formatting diagnostic messages.
|
|
</DL>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>INPUT FILES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="14"><I>/etc/X11/Xsession.d/</I>
|
|
|
|
<DD>
|
|
is a directory containing Bourne shell scripts to be executed by
|
|
<I>Xsession</I>.
|
|
|
|
Files in this directory are matched using
|
|
<B>run-parts</B>
|
|
|
|
and are
|
|
<B>source</B>d,
|
|
|
|
not executed in a subshell.
|
|
<DT id="15"><I>/etc/X11/Xresources/</I>
|
|
|
|
<DD>
|
|
is a directory containing files corresponding to Debian package names, each of
|
|
which contains system-wide X resource settings for X clients from the
|
|
corresponding package.
|
|
The settings are loaded with
|
|
<B>xrdb -merge</B>.
|
|
|
|
Files in this directory are matched using
|
|
<B>run-parts</B>.
|
|
|
|
<DT id="16"><I>/etc/X11/Xsession.options</I>
|
|
|
|
<DD>
|
|
contains configuration options for the
|
|
<I>/etc/X11/Xsession</I>
|
|
|
|
script.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?5+Xsession.options">Xsession.options</A></B>(5)
|
|
|
|
for more information.
|
|
<DT id="17"><I>$HOME/.Xresources</I>
|
|
|
|
<DD>
|
|
contains X resources specific to the invoking user's environment.
|
|
The settings are loaded with
|
|
<B>xrdb -merge</B>.
|
|
|
|
Note that
|
|
<I>$HOME/.Xdefaults</I>
|
|
|
|
is a relic from X Version 10 (and X11R1) days, before app-defaults files
|
|
were implemented.
|
|
It has been deprecated for over ten years at the time of this writing.
|
|
<I>.Xresources</I>
|
|
|
|
should be used instead.
|
|
<DT id="18"><I>$HOME/.xsession</I>
|
|
|
|
<DD>
|
|
is a sequence of commands invoking X clients (or a session manager such as
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xsm">xsm</A></B>(1)).
|
|
|
|
See the manual page for
|
|
<B>xinit</B>
|
|
|
|
for tips on writing an
|
|
<I>.xsession</I>
|
|
|
|
file.
|
|
</DL>
|
|
<A NAME="lbAL"> </A>
|
|
<H2>OUTPUT FILES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="19"><I>$HOME/.xsession-errors</I>
|
|
|
|
<DD>
|
|
is where standard output and standard error for
|
|
<I>Xsession</I>
|
|
|
|
script and all X client processes are directed by default.
|
|
<DT id="20"><I>$TMPDIR/filename</I>
|
|
|
|
<DD>
|
|
is where the X session error file is placed if
|
|
<I>$HOME/.xsession-errors</I>
|
|
|
|
cannot be opened.
|
|
For security reasons, the exact filename is randomly generated by
|
|
<B><A HREF="/cgi-bin/man/man2html?1+tempfile">tempfile</A></B>(1).
|
|
|
|
</DL>
|
|
<A NAME="lbAM"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
Stephen Early, Mark Eichin, and Branden Robinson developed Debian's X
|
|
session handling scripts.
|
|
Branden Robinson wrote this manual page.
|
|
<A NAME="lbAN"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?5+Xsession.options">Xsession.options</A></B>(5),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+X">X</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+run-parts">run-parts</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+ssh-agent">ssh-agent</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+startx">startx</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+tempfile">tempfile</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xdm">xdm</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xmessage">xmessage</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xmodmap">xmodmap</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+xrdb">xrdb</A></B>(1),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+sh">sh</A></B>(1)
|
|
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="21"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="22"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="23"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="24"><A HREF="#lbAE">SESSION TYPES</A><DD>
|
|
<DT id="25"><A HREF="#lbAF">DEFAULT STARTUP PROCEDURE</A><DD>
|
|
<DT id="26"><A HREF="#lbAG">SUPPLIED SCRIPTS</A><DD>
|
|
<DT id="27"><A HREF="#lbAH">CUSTOMIZING THE STARTUP PROCEDURE</A><DD>
|
|
<DT id="28"><A HREF="#lbAI">BUILT-IN SHELL FUNCTIONS</A><DD>
|
|
</DL>
|
|
<DT id="29"><A HREF="#lbAJ">ENVIRONMENT</A><DD>
|
|
<DT id="30"><A HREF="#lbAK">INPUT FILES</A><DD>
|
|
<DT id="31"><A HREF="#lbAL">OUTPUT FILES</A><DD>
|
|
<DT id="32"><A HREF="#lbAM">AUTHORS</A><DD>
|
|
<DT id="33"><A HREF="#lbAN">SEE ALSO</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:06:06 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|