debian/local/xvfb-run.1

   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: