trunk/xorg-server/xvfb-run.1

.\" $Id: xvfb-run.1 2138 2005-01-17 23:40:27Z branden $
.\"
.\" Copyright 1998-2004 Branden Robinson <branden@debian.org>.
.\"
.\" This is free software; you may redistribute it and/or modify
.\" it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2,
.\" or (at your option) any later version.
.\"
.\" This is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License with
.\" the Debian operating system, in /usr/share/common-licenses/GPL;  if
.\" not, write to the Free Software Foundation, Inc., 59 Temple Place,
.\" Suite 330, Boston, MA 02111-1307 USA
.\"
.\" We need the URL macro from groff's www macro package, but also want
.\" things to work all right for people who don't have it.  So we define
.\" our own URL macro and let the www macro package override it if it's
.\" available.
.de URL
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
.TH xvfb\-run 1 "2004\-11\-12" "Debian Project"
.SH NAME
xvfb\-run \- run specified X client or command in a virtual X server environment
.SH SYNOPSIS
.B xvfb\-run
[
.I options
]
.I command
.SH DESCRIPTION
.B xvfb\-run
is a wrapper for the
.BR Xvfb (1x)
command which simplifies the task of running commands (typically an X
client, or a script containing a list of clients to be run) within a virtual
X server environment.
.PP
.B xvfb\-run
sets up an X authority file (or uses an existing user\-specified one),
writes a cookie to it (see
.BR xauth (1x))
and then starts the
.B Xvfb
X server as a background process.
The process ID of
.B Xvfb
is stored for later use.
The specified
.I command
is then run using the X display corresponding to the
.B Xvfb
server
just started and the X authority file created earlier.
.PP
When the
.I command
exits, its status is saved, the
.B Xvfb
server is killed (using the process ID stored earlier), the X authority
cookie removed, and the authority file deleted (if the user did not specify
one to use).
.B xvfb\-run
then exits with the exit status of
.IR command .
.PP
.B xvfb\-run
requires the
.B xauth
command to function.
.SH OPTIONS
.TP
.B \-a\fR,\fB \-\-auto\-servernum
Try to get a free server number, starting at 99, or the argument to
.BR \-\-server\-num .
.TP
.BI \-e\  file \fR,\fB\ \-\-error\-file= file
Store output from
.B xauth
and
.B Xvfb
in
.IR file .
The default is
.IR /dev/null .
.TP
.BI \-f\  file \fR,\fB\ \-\-auth\-file= file
Store X authentication data in
.IR file .
By default, a temporary directory called
.IR xvfb\-run. PID
(where PID is the process ID of
.B xvfb\-run
itself) is created in the directory specified by the environment variable
.B TMPDIR
(or
.I /tmp
if that variable is null or unset), and the
.BR tempfile (1)
command is used to create a file in that temporary directory called
.IR Xauthority .
.TP
.B \-h\fR,\fB \-\-help
Display a usage message and exit.
.TP
.BI \-n\  servernumber \fR,\fB\ \-\-server\-num= servernumber
Use
.I servernumber
as the server number (but see the
.B \-a\fR,\fB \-\-auto\-servernum
option above).
The default is 99.
.TP
.B \-l\fR,\fB \-\-listen\-tcp
Enable TCP port listening in the X server.
For security reasons (to avoid denial\-of\-service attacks or exploits),
TCP port listening is disabled by default.
.TP
.BI \-p\  protocolname \fR,\fB\ \-\-xauth\-protocol= protocolname
Use
.I protocolname
as the X authority protocol to use.
The default is \(oq.\(cq, which
.B xauth
interprets as its own default protocol, which is MIT\-MAGIC\-COOKIE\-1.
.TP
.BI \-s\  arguments \fR,\fB\ \-\-server\-args= arguments
Pass
.I arguments
to the
.B Xvfb
server.
Be careful to quote any whitespace characters that may occur within
.I arguments
to prevent them from regarded as separators for
.BR xvfb\-run 's
own arguments.
Also, note that specification of \(oq\-nolisten tcp\(cq in
.I arguments
may override the function of
.BR xvfb\-run 's
own
.B \-l\fR,\fB \-\-listen\-tcp
option, and that specification of the server number (e.g., \(oq:1\(cq) may
be ignored because of the way the X server parses its argument list.
Use the
.B xvfb\-run
option
.BI \-n\  servernumber \fR,\fB\ \-\-server\-num= servernumber
to achieve the latter function.
The default is \(oq\-screen 0 640x480x8\(cq.
.TP
.BI \-w\  delay \fR,\fB\ \-\-wait= delay
Wait
.I delay
seconds after launching
.B Xvfb
before attempting to start the specified command.
The default is 3.
.SH ENVIRONMENT
.TP
.B COLUMNS
indicates the width of the terminal device in character cells.
This value is used for formatting diagnostic messages.
If not set, the terminal is queried using
.BR stty (1)
to determine its width.
If that fails, a value of \(oq80\(cq is assumed.
.TP
.B TMPDIR
specifies the directory in which to place
.BR xvfb\-run 's
temporary directory for storage of the X authority file; only used if the
.B \-f
or
.B \-\-auth\-file
options are not specified.
.SH "OUTPUT FILES"
.PP
Unless the
.B \-f
or
.B \-\-auth\-file
options are specified, a temporary
directory and file within it are created (and deleted) to store the X
authority cookies used by the
.B Xvfb
server and client(s) run under it.
See
.BR tempfile (1).
If \-f or \-\-auth\-file are used, then the specified X authority file is
only written to, not created or deleted (though
.B xauth
creates an authority file itself if told to use use that does not already
exist).
.PP
An error file with a user\-specified name is also created if the
.B \-e
or
.B \-\-error\-file
options are specifed; see above.
.SH "EXIT STATUS"
.B xvfb\-run
uses its exit status as well as output to standard error to communicate
diagnostics.
The exit status of \(oq1\(cq is not used, and should be interpreted as failure
of the specified command.
.TP
0
.B xvfb\-run
only uses this exit status if the
.B \-h\fR,\fB \-\-help
option is given.
In all other situations, this may be interpreted as success of the specified
command.
.TP
2
No command to run was specified.
.TP
3
The
.B xauth
command is not available.
.TP
4
The temporary directory that was going to be used already exists; since
.B xvfb\-run
produces a uniquely named directory, this may indicate an attempt by another
process on the system to exploit a temporary file race condition.
.TP
5
A problem was encountered while cleaning up the temporary directory.
.TP
6
A problem was encountered while using
.BR getopt (1)
to parse the command\-line arguments.
.SH EXAMPLES
.TP
.B xvfb\-run \-\-auto\-servernum \-\-server\-num=1 xlogo
runs the
.BR xlogo (1x)
demonstration client inside the
.B Xvfb
X server on the first available server number greater than or equal to 1.
.TP
.B xvfb\-run \-\-server\-args="\-screen 0 1024x768x24" ico \-faces
runs the
.BR ico (1x)
demonstration client (and passes it the
.B \-faces
argument) inside the
.B Xvfb
X server, configured with a root window of 1024 by 768 pixels and a color
depth of 24 bits.
.PP
Note that the demo X clients used in the above examples will not exit on
their own, so they will have to be killed before
.B xvfb\-run
will exit.
.SH BUGS
See
.URL "http://bugs.debian.org/xvfb" "the Debian Bug Tracking System" .
If you wish to report a bug in
.BR xvfb\-run ,
please use the 
.BR reportbug (1)
command.
.SH AUTHOR
.B xfvb\-run
was written by Branden Robinson and Jeff Licquia with sponsorship from
Progeny Linux Systems.
.SH "SEE ALSO"
.BR Xvfb (1x),
.BR xauth (1x)
.\" vim:set et tw=80:
1	niro	2695	.\" $Id: xvfb-run.1 2138 2005-01-17 23:40:27Z branden $
2			.\"
3			.\" Copyright 1998-2004 Branden Robinson <branden@debian.org>.
4			.\"
5			.\" This is free software; you may redistribute it and/or modify
6			.\" it under the terms of the GNU General Public License as
7			.\" published by the Free Software Foundation; either version 2,
8			.\" or (at your option) any later version.
9			.\"
10			.\" This is distributed in the hope that it will be useful, but
11			.\" WITHOUT ANY WARRANTY; without even the implied warranty of
12			.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13			.\" GNU General Public License for more details.
14			.\"
15			.\" You should have received a copy of the GNU General Public License with
16			.\" the Debian operating system, in /usr/share/common-licenses/GPL; if
17			.\" not, write to the Free Software Foundation, Inc., 59 Temple Place,
18			.\" Suite 330, Boston, MA 02111-1307 USA
19			.\"
20			.\" We need the URL macro from groff's www macro package, but also want
21			.\" things to work all right for people who don't have it. So we define
22			.\" our own URL macro and let the www macro package override it if it's
23			.\" available.
24			.de URL
25			\\$2 \(laURL: \\$1 \(ra\\$3
26			..
27			.if \n[.g] .mso www.tmac
28			.TH xvfb\-run 1 "2004\-11\-12" "Debian Project"
29			.SH NAME
30			xvfb\-run \- run specified X client or command in a virtual X server environment
31			.SH SYNOPSIS
32			.B xvfb\-run
33			[
34			.I options
35			]
36			.I command
37			.SH DESCRIPTION
38			.B xvfb\-run
39			is a wrapper for the
40			.BR Xvfb (1x)
41			command which simplifies the task of running commands (typically an X
42			client, or a script containing a list of clients to be run) within a virtual
43			X server environment.
44			.PP
45			.B xvfb\-run
46			sets up an X authority file (or uses an existing user\-specified one),
47			writes a cookie to it (see
48			.BR xauth (1x))
49			and then starts the
50			.B Xvfb
51			X server as a background process.
52			The process ID of
53			.B Xvfb
54			is stored for later use.
55			The specified
56			.I command
57			is then run using the X display corresponding to the
58			.B Xvfb
59			server
60			just started and the X authority file created earlier.
61			.PP
62			When the
63			.I command
64			exits, its status is saved, the
65			.B Xvfb
66			server is killed (using the process ID stored earlier), the X authority
67			cookie removed, and the authority file deleted (if the user did not specify
68			one to use).
69			.B xvfb\-run
70			then exits with the exit status of
71			.IR command .
72			.PP
73			.B xvfb\-run
74			requires the
75			.B xauth
76			command to function.
77			.SH OPTIONS
78			.TP
79			.B \-a\fR,\fB \-\-auto\-servernum
80			Try to get a free server number, starting at 99, or the argument to
81			.BR \-\-server\-num .
82			.TP
83			.BI \-e\ file \fR,\fB\ \-\-error\-file= file
84			Store output from
85			.B xauth
86			and
87			.B Xvfb
88			in
89			.IR file .
90			The default is
91			.IR /dev/null .
92			.TP
93			.BI \-f\ file \fR,\fB\ \-\-auth\-file= file
94			Store X authentication data in
95			.IR file .
96			By default, a temporary directory called
97			.IR xvfb\-run. PID
98			(where PID is the process ID of
99			.B xvfb\-run
100			itself) is created in the directory specified by the environment variable
101			.B TMPDIR
102			(or
103			.I /tmp
104			if that variable is null or unset), and the
105			.BR tempfile (1)
106			command is used to create a file in that temporary directory called
107			.IR Xauthority .
108			.TP
109			.B \-h\fR,\fB \-\-help
110			Display a usage message and exit.
111			.TP
112			.BI \-n\ servernumber \fR,\fB\ \-\-server\-num= servernumber
113			Use
114			.I servernumber
115			as the server number (but see the
116			.B \-a\fR,\fB \-\-auto\-servernum
117			option above).
118			The default is 99.
119			.TP
120			.B \-l\fR,\fB \-\-listen\-tcp
121			Enable TCP port listening in the X server.
122			For security reasons (to avoid denial\-of\-service attacks or exploits),
123			TCP port listening is disabled by default.
124			.TP
125			.BI \-p\ protocolname \fR,\fB\ \-\-xauth\-protocol= protocolname
126			Use
127			.I protocolname
128			as the X authority protocol to use.
129			The default is \(oq.\(cq, which
130			.B xauth
131			interprets as its own default protocol, which is MIT\-MAGIC\-COOKIE\-1.
132			.TP
133			.BI \-s\ arguments \fR,\fB\ \-\-server\-args= arguments
134			Pass
135			.I arguments
136			to the
137			.B Xvfb
138			server.
139			Be careful to quote any whitespace characters that may occur within
140			.I arguments
141			to prevent them from regarded as separators for
142			.BR xvfb\-run 's
143			own arguments.
144			Also, note that specification of \(oq\-nolisten tcp\(cq in
145			.I arguments
146			may override the function of
147			.BR xvfb\-run 's
148			own
149			.B \-l\fR,\fB \-\-listen\-tcp
150			option, and that specification of the server number (e.g., \(oq:1\(cq) may
151			be ignored because of the way the X server parses its argument list.
152			Use the
153			.B xvfb\-run
154			option
155			.BI \-n\ servernumber \fR,\fB\ \-\-server\-num= servernumber
156			to achieve the latter function.
157			The default is \(oq\-screen 0 640x480x8\(cq.
158			.TP
159			.BI \-w\ delay \fR,\fB\ \-\-wait= delay
160			Wait
161			.I delay
162			seconds after launching
163			.B Xvfb
164			before attempting to start the specified command.
165			The default is 3.
166			.SH ENVIRONMENT
167			.TP
168			.B COLUMNS
169			indicates the width of the terminal device in character cells.
170			This value is used for formatting diagnostic messages.
171			If not set, the terminal is queried using
172			.BR stty (1)
173			to determine its width.
174			If that fails, a value of \(oq80\(cq is assumed.
175			.TP
176			.B TMPDIR
177			specifies the directory in which to place
178			.BR xvfb\-run 's
179			temporary directory for storage of the X authority file; only used if the
180			.B \-f
181			or
182			.B \-\-auth\-file
183			options are not specified.
184			.SH "OUTPUT FILES"
185			.PP
186			Unless the
187			.B \-f
188			or
189			.B \-\-auth\-file
190			options are specified, a temporary
191			directory and file within it are created (and deleted) to store the X
192			authority cookies used by the
193			.B Xvfb
194			server and client(s) run under it.
195			See
196			.BR tempfile (1).
197			If \-f or \-\-auth\-file are used, then the specified X authority file is
198			only written to, not created or deleted (though
199			.B xauth
200			creates an authority file itself if told to use use that does not already
201			exist).
202			.PP
203			An error file with a user\-specified name is also created if the
204			.B \-e
205			or
206			.B \-\-error\-file
207			options are specifed; see above.
208			.SH "EXIT STATUS"
209			.B xvfb\-run
210			uses its exit status as well as output to standard error to communicate
211			diagnostics.
212			The exit status of \(oq1\(cq is not used, and should be interpreted as failure
213			of the specified command.
214			.TP
215			0
216			.B xvfb\-run
217			only uses this exit status if the
218			.B \-h\fR,\fB \-\-help
219			option is given.
220			In all other situations, this may be interpreted as success of the specified
221			command.
222			.TP
223			2
224			No command to run was specified.
225			.TP
226			3
227			The
228			.B xauth
229			command is not available.
230			.TP
231			4
232			The temporary directory that was going to be used already exists; since
233			.B xvfb\-run
234			produces a uniquely named directory, this may indicate an attempt by another
235			process on the system to exploit a temporary file race condition.
236			.TP
237			5
238			A problem was encountered while cleaning up the temporary directory.
239			.TP
240			6
241			A problem was encountered while using
242			.BR getopt (1)
243			to parse the command\-line arguments.
244			.SH EXAMPLES
245			.TP
246			.B xvfb\-run \-\-auto\-servernum \-\-server\-num=1 xlogo
247			runs the
248			.BR xlogo (1x)
249			demonstration client inside the
250			.B Xvfb
251			X server on the first available server number greater than or equal to 1.
252			.TP
253			.B xvfb\-run \-\-server\-args="\-screen 0 1024x768x24" ico \-faces
254			runs the
255			.BR ico (1x)
256			demonstration client (and passes it the
257			.B \-faces
258			argument) inside the
259			.B Xvfb
260			X server, configured with a root window of 1024 by 768 pixels and a color
261			depth of 24 bits.
262			.PP
263			Note that the demo X clients used in the above examples will not exit on
264			their own, so they will have to be killed before
265			.B xvfb\-run
266			will exit.
267			.SH BUGS
268			See
269			.URL "http://bugs.debian.org/xvfb" "the Debian Bug Tracking System" .
270			If you wish to report a bug in
271			.BR xvfb\-run ,
272			please use the
273			.BR reportbug (1)
274			command.
275			.SH AUTHOR
276			.B xfvb\-run
277			was written by Branden Robinson and Jeff Licquia with sponsorship from
278			Progeny Linux Systems.
279			.SH "SEE ALSO"
280			.BR Xvfb (1x),
281			.BR xauth (1x)
282			.\" vim:set et tw=80: