1 .\" Copyright 1998-2004 Branden Robinson <branden@debian.org>.
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.
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.
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
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
23 \\$2 \(laURL: \\$1 \(ra\\$3
25 .if \n[.g] .mso www.tmac
26 .TH xvfb\-run 1 "2004\-11\-12" "Debian Project"
28 xvfb\-run \- run specified X client or command in a virtual X server environment
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
44 sets up an X authority file (or uses an existing user\-specified one),
45 writes a cookie to it (see
49 X server as a background process.
52 is stored for later use.
55 is then run using the X display corresponding to the
58 just started and the X authority file created earlier.
62 exits, its status is saved, the
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
68 then exits with the exit status of
70 except in error conditions (see
81 .B \-a\fR,\fB \-\-auto\-servernum
82 Try to get a free server number, starting at 99, or the argument to
85 .BI \-e\ file \fR,\fB\ \-\-error\-file= file
95 .BI \-f\ file \fR,\fB\ \-\-auth\-file= file
96 Store X authentication data in
98 By default, a temporary directory called
100 (where PID is the process ID of
102 itself) is created in the directory specified by the environment variable
106 if that variable is null or unset), and the
108 command is used to create a file in that temporary directory called
111 .B \-h\fR,\fB \-\-help
112 Display a usage message and exit.
114 .BI \-n\ servernumber \fR,\fB\ \-\-server\-num= servernumber
117 as the server number (but see the
118 .B \-a\fR,\fB \-\-auto\-servernum
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.
127 .BI \-p\ protocolname \fR,\fB\ \-\-xauth\-protocol= protocolname
130 as the X authority protocol to use.
131 The default is \(oq.\(cq, which
133 interprets as its own default protocol, which is MIT\-MAGIC\-COOKIE\-1.
135 .BI \-s\ arguments \fR,\fB\ \-\-server\-args= arguments
141 Be careful to quote any whitespace characters that may occur within
143 to prevent them from regarded as separators for
146 Also, note that specification of \(oq\-nolisten tcp\(cq in
148 may override the function of
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.
157 .BI \-n\ servernumber \fR,\fB\ \-\-server\-num= servernumber
158 to achieve the latter function.
159 The default is \(oq\-screen 0 640x480x8\(cq.
161 .BI \-w\ delay \fR,\fB\ \-\-wait= delay
162 Ignored for compatibility with earlier versions.
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
170 to determine its width.
171 If that fails, a value of \(oq80\(cq is assumed.
174 specifies the directory in which to place
176 temporary directory for storage of the X authority file; only used if the
180 options are not specified.
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
191 server and client(s) run under it.
194 If \-f or \-\-auth\-file are used, then the specified X authority file is
195 only written to, not created or deleted (though
197 creates an authority file itself if told to use use that does not already
200 An error file with a user\-specified name is also created if the
204 options are specifed; see above.
207 uses its exit status as well as output to standard error to communicate
212 only uses this exit status if the
213 .B \-h\fR,\fB \-\-help
215 In all other situations, this may be interpreted as success of the specified
220 did not start correctly.
223 No command to run was specified.
228 command is not available.
231 The temporary directory that was going to be used already exists; since
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.
237 A problem was encountered while cleaning up the temporary directory.
240 A problem was encountered while using
242 to parse the command\-line arguments.
245 .B xvfb\-run \-\-auto\-servernum \-\-server\-num=1 xlogo
248 demonstration client inside the
250 X server on the first available server number greater than or equal to 1.
252 .B xvfb\-run \-\-server\-args="\-screen 0 1024x768x24" ico \-faces
255 demonstration client (and passes it the
259 X server, configured with a root window of 1024 by 768 pixels and a color
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
268 .URL "http://bugs.debian.org/xvfb" "the Debian Bug Tracking System" .
269 If you wish to report a bug in
276 was written by Branden Robinson and Jeff Licquia with sponsorship from
277 Progeny Linux Systems.
281 .\" vim:set et tw=80: