Penguin
Recent Changes
Annotated edit history of Xsession(5) version 5, including all changes. View license author blame.
Rev Author # Line
1 perry 1 Xsession
2 !!!Xsession
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 ENVIRONMENT
7 INPUT FILES
8 OUTPUT FILES
9 SEE ALSO
10 AUTHOR
11 ----
12 !!NAME
13
14
15 Xsession - initialize X session
16 !!SYNOPSIS
17
18
19 Xsession [[ ''session-type'' ]
20 !!DESCRIPTION
21
22
23 ''/etc/X11/Xsession'' is a Bourne shell (sh(1))
24 script which is run every time an X Window System session is
25 begun by startx(1) or a display manager such as
26 xdm(1). (Some display managers only invoke
27 ''Xsession'' when specifically directed to so by the
28 user; see the documentation for your display manager to find
29 out more.) Administrators unfamilar with the Bourne shell
5 perry 30 will likely find the Xsession.options(5)
1 perry 31 configuration file easier to deal with than ''Xsession''
32 itself.
33
34
35 ''Xsession'' is not intended to be invoked directly by
36 the user; to be effective it needs to run in a special
37 environment associated with X server initialization.
38 startx(1), xdm(1), xinit(1), and other
39 similar programs handle this.
40
41
42 By default on a Debian system, ''Xsession'' is used by
43 both common methods of starting the X Window System,
44 __xdm__ and __startx__. To change this for __xdm,__
45 edit the
46 __/etc/X11/xdm/xdm-config'' file; for __startx__,
47 replace the contents of the ''/etc/X11/xinit/xinitrc''
48 file.
49
50
51 The ''Xsession'' script is quite flexible, and extensive
52 customization of the X startup procedure is possible without
53 modifying the script itself. See
54 ''
55
56
57 __SESSION TYPES__
58
59
60 ''Xsession'' may optionally be passed a single argument
61 indicating the type of X session to be started. It is up to
62 the display manager to set the argument. By default, three
63 different arguments are supported:
64
65
66 failsafe
67
68
69 invokes a session consisting solely of
70 ''/usr/bin/x-terminal-emulator'' (no window manager is
71 launched). If the x-terminal-emulator program cannot be
72 found, the session exits. The
73 ''Xsession.options''.
74
75
76 default
77
78
79 produces the same behavior as if no session type argument
80 had been given at all.
81
82
83 ''program''
84
85
86 starts ''program'' if it can be found in the $PATH. This
87 is usually a session manager or a very featureful window
88 manager. If ''program'' is not found, the ''Xsession''
89 script proceeds with its default behavior. This argument is
90 ignored if there is no
91 ''Xsession.options''. (The reason being, if the
92 administrator does not want users writing their own
93 ''.Xsession'' files, it makes little sense to permit them
94 to specify the names of arbitrary programs to
95 run.)
96
97
98 __DEFAULT STARTUP PROCEDURE__
99
100
101 Initially, ''Xsession'' performs some housekeeping. It
102 declares a set of built-in functions (see
103 ''
104
105
106 ''Xsession'' next confirms that its script directory,
107 ''Xsession.d'', exists. If it does not, the script
108 aborts. After the script directory is confirmed to be
109 present, ''Xsession'' uses an internal implementation of
5 perry 110 run-parts(1) to identify files in that directory that
1 perry 111 should be sourced (executed) in the shell's environment.
112 Only files named in a certain way are sourced; see the
5 perry 113 run-parts(1) manual page for a description of valid
1 perry 114 characters in the filename. (This restriction enables the
115 administrator to move experimental or problematic files out
116 of the way of the script but keep them in an obvious place,
117 for instance by renaming them with
118 __
119
120
121 Five scripts are provided by default:
122
123
124 1) Argument processing. Arguments are processed as described
125 in
126
127
5 perry 128 2) Merging of X resources. run-parts(1) is again
1 perry 129 used, this time to identify files in the
130 ''/etc/X11/Xresources'' directory that should be
131 processed with
132 ''Xsession.options'', the user's ''$HOME/.Xresources''
133 file is merged in the same way.
134
135
136 3) Determine startup program. The X client to launch as the
137 controlling process (the one that, upon exiting, causes the
138 X server to exit as well) is determined next. If the line
139 Xsession.options'', a user-specified session program or
140 script is used. If a program or failsafe argument was given
141 and is allowed (see above), it is used instead. Otherwise,
142 two historically popular names for user X session scripts
143 are searched for: ''$HOME/.xsession'' and
144 ''$HOME/.Xsession'' (note the difference in case). The
145 first one found is used. If the script is not executable, it
146 is marked to be executed with the Bourne shell interpreter,
147 sh(1). If
148 __/usr/bin/x-session-manager'',
149 ''/usr/bin/x-window-manager'', and
150 ''/usr/bin/x-terminal-emulator''. The first one found is
151 used. If none are found, ''Xsession'' aborts with an
152 error.
153
154
155 4) Start ssh-agent, if needed. If the line
156 Xsession.options'', and no ssh agent process appears to
5 perry 157 be running already, ssh-agent(1) is marked to be used
1 perry 158 to execute the startup program determined previously.
159 ''Note: this functionality may move to the ssh package in
160 the future.''
161
162
163 5) Start the X session. Finally, the startup program is
164 executed, inside a Bourne shell if necessary, and inside an
165 ssh-agent if necessary. The shell's __exec__ command is
166 used to spare a slot in the process table.
167
168
169 __CUSTOMIZING THE STARTUP PROCEDURE__
170
171
172 Of course, any of the existing files can be edited
173 in-place.
174
175
176 Because the order in which the various scripts in
177 ''/etc/X11/Xsession.d'' are executed is important, files
178 to be added to this directory should have a well-formed
179 name. The following format is recommended:
180
181
182 * a two-digit number denoting sequence
183
184
185 * the name of the package providing the script
186
187
188 * an underscore
189
190
191 * a description of the script's basic function, using only
5 perry 192 characters allowed by run-parts(1).
1 perry 193
194
195 Here is an example of how one might write a script, named
196 ''40custom_load-xmodmap'', to invoke
197 xmodmap(1):
198
199
200 SYSMODMAP=/etc/X11/Xmodmap
201
202
203 USRMODMAP=$HOME/.Xmodmap
204
205
206 if [[ -x /usr/bin/X11/xmodmap ]; then
207
208
209 if [[ -f $SYSMODMAP ]; then
210
211
212 xmodmap $SYSMODMAP
213
214
215 fi
216
217
218 fi
219
220
221 if [[ -x /usr/bin/X11/xmodmap ]; then
222
223
224 if [[ -f $USRMODMAP ]; then
225
226
227 xmodmap $USRMODMAP
228
229
230 fi
231
232
233 fi
234
235
236 Those writing scripts for ''Xsession'' to execute should
237 avail themselves of its built-in shell functions, described
238 below.
239
240
241 __BUILT-IN SHELL FUNCTIONS__
242
243
244 __message__ is used for communicating with the user. It
245 may be given an arbitrarily long message string. It is
246 formatted to the user's terminal width (breaking lines at
247 whitespace) and sent to standard error.
248
249
250 __message_nonl__ is used for communicating with the user
251 when a trailing newline is undesirable. It may be given an
252 arbitrarily long message string. It is formatted to the
253 user's terminal width (breaking lines at whitespace) and
254 sent to standard error.
255
256
257 __errormsg__ is used for indicating an error condition
258 and aborting the script. It can be used as __message__
259 above. After displaying the message to standard error, it
260 will exit ''Xsession'' with status 1.
261 !!ENVIRONMENT
262
263
264 The following environment variables affect the execution of
265 ''Xsession'':
266
267
268 HOME
269
270
271 The user's home directory; various files are searched for
272 here.
273
274
275 TMPDIR
276
277
278 Default directory for temporary files; if the standard X
279 session error file cannot be opened, this variable is used
280 to locate a place for one.
281
282
283 COLUMNS
284
285
286 Width of terminal device, in character cells. Used for
287 formatting diagnostic messages.
288 !!INPUT FILES
289
290
291 ''/etc/X11/Xsession.d/''
292
293
294 is a directory containing Bourne shell scripts to be
295 executed by ''Xsession''. Files in this directory are
5 perry 296 matched using run-parts(1) and are __source__d,
1 perry 297 not executed in a subshell.
298
299
300 ''/etc/X11/Xresources/''
301
302
303 is a directory containing files corresponding to Debian
304 package names, each of which contains system-wide X resource
305 settings for X clients from the corresponding package. The
306 settings are loaded with __xrdb -merge__. Files in this
307 directory are matched using
5 perry 308 run-parts(1).
1 perry 309
310
311 ''/etc/X11/Xsession.options''
312
313
314 contains configuration options for the
315 ''/etc/X11/Xsession'' script. See
5 perry 316 Xsession.options(5) for more
1 perry 317 information.
318
319
320 ''$HOME/.Xresources''
321
322
323 contains X resources specific to the invoking user's
324 environment. The settings are loaded with __xrdb
325 -merge__. Note that ''$HOME/.Xdefaults'' is a relic
326 from X Version 10 (and X11R1) days, before app-defaults
327 files were implemented. It has been deprecated for over ten
328 years at the time of this writing. ''.Xresources'' should
329 be used instead.
330
331
332 ''$HOME/.Xsession''
333
334
335 is a sequence of commands invoking X clients (or a session
336 manager such as xsm(1)). See the manual page for
337 __xinit__ and/or
338 ''/usr/share/doc/xfree86-common/examples/xsession'' for
339 tips on writing an ''.Xsession'' file.
340 !!OUTPUT FILES
341
342
343 ''$HOME/.xsession-errors''
344
345
346 Where standard output and standard error for ''Xsession''
347 script and all X client processes are directed by
348 default.
349
350
351 ''$TMPDIR''
352
353
354 Where the X session error file is placed if
355 ''$HOME/.xsession-errors'' cannot be opened. The filename
356 is provided by tempfile(1).
357 !!SEE ALSO
358
359
5 perry 360 Xsession.options(5), __X__(1),
361 run-parts(1), __ssh-agent__(1), startx(1),
1 perry 362 tempfile(1), xdm(1), xmodmap(1),
363 xrdb(1), sh(1)
364 !!AUTHOR
365
366
367 ''/etc/X11/Xsession'' and its associated files in
368 ''/etc/X11/Xsession.d'' were written by Stephen Early,
369 Mark Eichin, and Branden Robinson.
370 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.