X-Git-Url: https://git.piment-noir.org/?p=deb_xorg-server.git;a=blobdiff_plain;f=debian%2Flocal%2Fxvfb-run.1;fp=debian%2Flocal%2Fxvfb-run.1;h=da6f606bffd8652215a983cc324ca2b7103e8863;hp=0000000000000000000000000000000000000000;hb=7217e0ca50bba73dad94782e67980aeeb24ab693;hpb=a09e091a5c996d46a398abb27b06fe504591673f diff --git a/debian/local/xvfb-run.1 b/debian/local/xvfb-run.1 new file mode 100644 index 0000000..da6f606 --- /dev/null +++ b/debian/local/xvfb-run.1 @@ -0,0 +1,281 @@ +.\" Copyright 1998-2004 Branden Robinson . +.\" +.\" This is free software; you may redistribute it and/or modify +.\" it under the terms of the GNU General Public License as +.\" published by the Free Software Foundation; either version 2, +.\" or (at your option) any later version. +.\" +.\" This is distributed in the hope that it will be useful, but +.\" WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License with +.\" the Debian operating system, in /usr/share/common-licenses/GPL; if +.\" not, write to the Free Software Foundation, Inc., 59 Temple Place, +.\" Suite 330, Boston, MA 02111-1307 USA +.\" +.\" We need the URL macro from groff's www macro package, but also want +.\" things to work all right for people who don't have it. So we define +.\" our own URL macro and let the www macro package override it if it's +.\" available. +.de URL +\\$2 \(laURL: \\$1 \(ra\\$3 +.. +.if \n[.g] .mso www.tmac +.TH xvfb\-run 1 "2004\-11\-12" "Debian Project" +.SH NAME +xvfb\-run \- run specified X client or command in a virtual X server environment +.SH SYNOPSIS +.B xvfb\-run +[ +.I options +] +.I command +.SH DESCRIPTION +.B xvfb\-run +is a wrapper for the +.BR Xvfb (1x) +command which simplifies the task of running commands (typically an X +client, or a script containing a list of clients to be run) within a virtual +X server environment. +.PP +.B xvfb\-run +sets up an X authority file (or uses an existing user\-specified one), +writes a cookie to it (see +.BR xauth (1x)) +and then starts the +.B Xvfb +X server as a background process. +The process ID of +.B Xvfb +is stored for later use. +The specified +.I command +is then run using the X display corresponding to the +.B Xvfb +server +just started and the X authority file created earlier. +.PP +When the +.I command +exits, its status is saved, the +.B Xvfb +server is killed (using the process ID stored earlier), the X authority +cookie removed, and the authority file deleted (if the user did not specify +one to use). +.B xvfb\-run +then exits with the exit status of +.IR command , +except in error conditions (see +.SM +.B EXIT STATUS +below). +.PP +.B xvfb\-run +requires the +.B xauth +command to function. +.SH OPTIONS +.TP +.B \-a\fR,\fB \-\-auto\-servernum +Try to get a free server number, starting at 99, or the argument to +.BR \-\-server\-num . +.TP +.BI \-e\ file \fR,\fB\ \-\-error\-file= file +Store output from +.B xauth +and +.B Xvfb +in +.IR file . +The default is +.IR /dev/null . +.TP +.BI \-f\ file \fR,\fB\ \-\-auth\-file= file +Store X authentication data in +.IR file . +By default, a temporary directory called +.IR xvfb\-run. PID +(where PID is the process ID of +.B xvfb\-run +itself) is created in the directory specified by the environment variable +.B TMPDIR +(or +.I /tmp +if that variable is null or unset), and the +.BR tempfile (1) +command is used to create a file in that temporary directory called +.IR Xauthority . +.TP +.B \-h\fR,\fB \-\-help +Display a usage message and exit. +.TP +.BI \-n\ servernumber \fR,\fB\ \-\-server\-num= servernumber +Use +.I servernumber +as the server number (but see the +.B \-a\fR,\fB \-\-auto\-servernum +option above). +The default is 99. +.TP +.B \-l\fR,\fB \-\-listen\-tcp +Enable TCP port listening in the X server. +For security reasons (to avoid denial\-of\-service attacks or exploits), +TCP port listening is disabled by default. +.TP +.BI \-p\ protocolname \fR,\fB\ \-\-xauth\-protocol= protocolname +Use +.I protocolname +as the X authority protocol to use. +The default is \(oq.\(cq, which +.B xauth +interprets as its own default protocol, which is MIT\-MAGIC\-COOKIE\-1. +.TP +.BI \-s\ arguments \fR,\fB\ \-\-server\-args= arguments +Pass +.I arguments +to the +.B Xvfb +server. +Be careful to quote any whitespace characters that may occur within +.I arguments +to prevent them from regarded as separators for +.BR xvfb\-run 's +own arguments. +Also, note that specification of \(oq\-nolisten tcp\(cq in +.I arguments +may override the function of +.BR xvfb\-run 's +own +.B \-l\fR,\fB \-\-listen\-tcp +option, and that specification of the server number (e.g., \(oq:1\(cq) may +be ignored because of the way the X server parses its argument list. +Use the +.B xvfb\-run +option +.BI \-n\ servernumber \fR,\fB\ \-\-server\-num= servernumber +to achieve the latter function. +The default is \(oq\-screen 0 640x480x8\(cq. +.TP +.BI \-w\ delay \fR,\fB\ \-\-wait= delay +Ignored for compatibility with earlier versions. +.SH ENVIRONMENT +.TP +.B COLUMNS +indicates the width of the terminal device in character cells. +This value is used for formatting diagnostic messages. +If not set, the terminal is queried using +.BR stty (1) +to determine its width. +If that fails, a value of \(oq80\(cq is assumed. +.TP +.B TMPDIR +specifies the directory in which to place +.BR xvfb\-run 's +temporary directory for storage of the X authority file; only used if the +.B \-f +or +.B \-\-auth\-file +options are not specified. +.SH "OUTPUT FILES" +.PP +Unless the +.B \-f +or +.B \-\-auth\-file +options are specified, a temporary +directory and file within it are created (and deleted) to store the X +authority cookies used by the +.B Xvfb +server and client(s) run under it. +See +.BR tempfile (1). +If \-f or \-\-auth\-file are used, then the specified X authority file is +only written to, not created or deleted (though +.B xauth +creates an authority file itself if told to use use that does not already +exist). +.PP +An error file with a user\-specified name is also created if the +.B \-e +or +.B \-\-error\-file +options are specifed; see above. +.SH "EXIT STATUS" +.B xvfb\-run +uses its exit status as well as output to standard error to communicate +diagnostics. +.TP +0 +.B xvfb\-run +only uses this exit status if the +.B \-h\fR,\fB \-\-help +option is given. +In all other situations, this may be interpreted as success of the specified +command. +.TP +1 +.B Xvfb +did not start correctly. +.TP +2 +No command to run was specified. +.TP +3 +The +.B xauth +command is not available. +.TP +4 +The temporary directory that was going to be used already exists; since +.B xvfb\-run +produces a uniquely named directory, this may indicate an attempt by another +process on the system to exploit a temporary file race condition. +.TP +5 +A problem was encountered while cleaning up the temporary directory. +.TP +6 +A problem was encountered while using +.BR getopt (1) +to parse the command\-line arguments. +.SH EXAMPLES +.TP +.B xvfb\-run \-\-auto\-servernum \-\-server\-num=1 xlogo +runs the +.BR xlogo (1x) +demonstration client inside the +.B Xvfb +X server on the first available server number greater than or equal to 1. +.TP +.B xvfb\-run \-\-server\-args="\-screen 0 1024x768x24" ico \-faces +runs the +.BR ico (1x) +demonstration client (and passes it the +.B \-faces +argument) inside the +.B Xvfb +X server, configured with a root window of 1024 by 768 pixels and a color +depth of 24 bits. +.PP +Note that the demo X clients used in the above examples will not exit on +their own, so they will have to be killed before +.B xvfb\-run +will exit. +.SH BUGS +See +.URL "http://bugs.debian.org/xvfb" "the Debian Bug Tracking System" . +If you wish to report a bug in +.BR xvfb\-run , +please use the +.BR reportbug (1) +command. +.SH AUTHOR +.B xvfb\-run +was written by Branden Robinson and Jeff Licquia with sponsorship from +Progeny Linux Systems. +.SH "SEE ALSO" +.BR Xvfb (1x), +.BR xauth (1x) +.\" vim:set et tw=80: