Contents of /trunk/xorg-server/xvfb-run.1
Parent Directory | Revision Log
Revision 2695 -
(show annotations)
(download)
Mon Sep 14 09:19:36 2015 UTC (9 years ago) by niro
File size: 7569 byte(s)
Mon Sep 14 09:19:36 2015 UTC (9 years ago) by niro
File size: 7569 byte(s)
-added xvfb-run man file
1 | .\" $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: |