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