Commit | Line | Data |
---|---|---|
7217e0ca ML |
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: |