| 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: |