Annotation of /trunk/xorg-server/xvfb-run.1
Parent Directory | Revision Log
Revision 2695 -
(hide 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 | 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: |