Author: branden
Date: 2004-11-16 09:54:16 -0500 (Tue, 16 Nov 2004)
New Revision: 2027
Modified:
trunk/debian/CHANGESETS
trunk/debian/changelog
trunk/debian/local/xvfb-run
trunk/debian/local/xvfb-run.1
Log:
Perform some cleanup work on the xvfb-run utility and its manual page.
+ Query terminal for its width if $COLUMNS is not set, as shell-lib.sh
does. Fall back to a width of 80 if stty returns garbage or nothing.
+ Add message() and error() functions.
+ Enhance usage() function to (additionally) display an error message
consisting of the function arguments, if any.
+ Use error() and usage() instead of echo for error messages.
+ Cosmetically tidy up usage message, and correct a typo.
+ Declare locally-scoped variable in find_free_servernum().
+ Store getopt's exit status and report it in an error message if it is
nonzero.
+ Clarify the error message if getopt rearranges the command line in a way
we don't expect.
+ Tidy up comment, shell function, and redirection style. Wrap long
lines. Quote variables that may have whitespace in them. Update Vim
modeline.
+ Describe effect of $COLUMNS environment variable in manpage.
+ Remove erroneous description of exit status 1, and explain why it is not
used.
+ Add description of exit statuses 0, 4, 5, and 6.
+ Fix markup error.
Set svn:keywords property to "Id" on xvfb-run.
Set svn:executable property to "*" on xvfb-run.
Modified: trunk/debian/CHANGESETS
===================================================================
--- trunk/debian/CHANGESETS 2004-11-12 06:00:26 UTC (rev 2026)
+++ trunk/debian/CHANGESETS 2004-11-16 14:54:16 UTC (rev 2027)
@@ -283,4 +283,27 @@
are no backwards-incomaptible changes).
2025, 2026
+Perform some cleanup work on the xvfb-run utility and its manual page.
++ Query terminal for its width if $COLUMNS is not set, as shell-lib.sh
+ does. Fall back to a width of 80 if stty returns garbage or nothing.
++ Add message() and error() functions.
++ Enhance usage() function to (additionally) display an error message
+ consisting of the function arguments, if any.
++ Use error() and usage() instead of echo for error messages.
++ Cosmetically tidy up usage message, and correct a typo.
++ Declare locally-scoped variable in find_free_servernum().
++ Store getopt's exit status and report it in an error message if it is
+ nonzero.
++ Clarify the error message if getopt rearranges the command line in a way
+ we don't expect.
++ Tidy up comment, shell function, and redirection style. Wrap long
+ lines. Quote variables that may have whitespace in them. Update Vim
+ modeline.
++ Describe effect of $COLUMNS environment variable in manpage.
++ Remove erroneous description of exit status 1, and explain why it is not
+ used.
++ Add description of exit statuses 0, 4, 5, and 6.
++ Fix markup error.
+ 2027
+
vim:set ai et sts=4 sw=4 tw=80:
Modified: trunk/debian/changelog
===================================================================
--- trunk/debian/changelog 2004-11-12 06:00:26 UTC (rev 2026)
+++ trunk/debian/changelog 2004-11-16 14:54:16 UTC (rev 2027)
@@ -160,6 +160,28 @@
+ Update manual pages to document changes in interface and behavior (there
are no backwards-incomaptible changes).
+ * Perform some cleanup work on the xvfb-run utility and its manual page.
+ + Query terminal for its width if $COLUMNS is not set, as shell-lib.sh
+ does. Fall back to a width of 80 if stty returns garbage or nothing.
+ + Add message() and error() functions.
+ + Enhance usage() function to (additionally) display an error message
+ consisting of the function arguments, if any.
+ + Use error() and usage() instead of echo for error messages.
+ + Cosmetically tidy up usage message, and correct a typo.
+ + Declare locally-scoped variable in find_free_servernum().
+ + Store getopt's exit status and report it in an error message if it is
+ nonzero.
+ + Clarify the error message if getopt rearranges the command line in a way
+ we don't expect.
+ + Tidy up comment, shell function, and redirection style. Wrap long
+ lines. Quote variables that may have whitespace in them. Update Vim
+ modeline.
+ + Describe effect of $COLUMNS environment variable in manpage.
+ + Remove erroneous description of exit status 1, and explain why it is not
+ used.
+ + Add description of exit statuses 0, 4, 5, and 6.
+ + Fix markup error.
+
Changes by Denis Barbier and Fabio M. Di Nitto:
* Edit xc/programs/xkbcomp/symbols/pc/Imakefile so that the new pc/us_intl
@@ -242,7 +264,7 @@
exiting upon encountering the first shell interpeter that fails on the
script; instead, attempt all the interpreters and report all that fail.
- -- Branden Robinson <[EMAIL PROTECTED]> Fri, 12 Nov 2004 00:50:58 -0500
+ -- Branden Robinson <[EMAIL PROTECTED]> Fri, 12 Nov 2004 17:07:29 -0500
xfree86 (4.3.0.dfsg.1-8) unstable; urgency=high
Modified: trunk/debian/local/xvfb-run
===================================================================
--- trunk/debian/local/xvfb-run 2004-11-12 06:00:26 UTC (rev 2026)
+++ trunk/debian/local/xvfb-run 2004-11-16 14:54:16 UTC (rev 2027)
@@ -1,14 +1,13 @@
#!/bin/sh
-# xvfb-run - run the specified command in a virtual X server
+# $Id$
-# This script starts an instance of Xvfb, the "fake" X server, runs a
-# command with that server available, and kills the X server when
-# done. The return value of the command becomes the return value of
-# this script.
+# This script starts an instance of Xvfb, the "fake" X server, runs a command
+# with that server available, and kills the X server when done. The return
+# value of the command becomes the return value of this script.
#
-# If anyone is using this to build a Debian package, make sure the
-# package Build-Depends on xvfb, xbase-clients, and xfonts-base.
+# If anyone is using this to build a Debian package, make sure the package
+# Build-Depends on xvfb, xbase-clients, and xfonts-base.
set -e
@@ -21,51 +20,73 @@
LISTENTCP="-nolisten tcp"
XAUTHPROTO=.
-# display a usage message
+# Query the terminal to establish a default number of columns to use for
+# displaying messages to the user. This is used only as a fallback in the
event
+# the COLUMNS variable is not set. ($COLUMNS can react to SIGWINCH while the
+# script is running, and this cannot, only being calculated once.)
+DEFCOLUMNS=$(stty size 2>/dev/null | awk '{print $2}') || true
+if ! expr "$DEFCOLUMNS" : "[[:digit:]]\+$" >/dev/null 2>&1; then
+ DEFCOLUMNS=80
+fi
+
+# Display a message, wrapping lines at the terminal width.
+message () {
+ echo "$PROGNAME: $*" | fmt -t -w ${COLUMNS:-$DEFCOLUMNS}
+}
+
+# Display an error message.
+error () {
+ message "error: $*" >&2
+}
+
+# Display a usage message.
usage () {
- cat << EOF
+ if [ -n "$*" ]; then
+ message "usage error: $*"
+ fi
+ cat <<EOF
Usage: $PROGNAME [OPTION ...] COMMAND
-
-run COMMAND (usually an X client) in a virtual X server environment
-
+Run COMMAND (usually an X client) in a virtual X server environment.
Options:
--a --auto-servernum try to get a free server number, starting at
- --server-num
--e FILE --error-file=FILE file used to store xauth errors and Xvfb output
- (defualt: $ERRORFILE)
--f FILE --auth-file=FILE file used to store auth cookie
- (default: ./.Xauthority)
--h --help display this usage message and exit
--n NUM --server-num=NUM server number to use (default: $SERVERNUM)
--l --listen-tcp enable TCP port listening in the X server
--p PROTO --xauth-protocol=PROTO X authority protocol name to use
- (defaults to xauth's default)
--s ARGS --server-args=ARGS arguments (other than server number and -nolisten
- tcp) to pass to the Xvfb server
- (default: \"$XVFBARGS\")
--w DELAY --wait=DELAY delay in seconds to wait for Xvfb to start
- (default: $STARTWAIT)
+-a --auto-servernum try to get a free server number, starting
at
+ --server-num
+-e FILE --error-file=FILE file used to store xauth errors and Xvfb
+ output (default: $ERRORFILE)
+-f FILE --auth-file=FILE file used to store auth cookie
+ (default: ./.Xauthority)
+-h --help display this usage message and exit
+-n NUM --server-num=NUM server number to use (default: $SERVERNUM)
+-l --listen-tcp enable TCP port listening in the X server
+-p PROTO --xauth-protocol=PROTO X authority protocol name to use
+ (default: xauth command's default)
+-s ARGS --server-args=ARGS arguments (other than server number and
+ "-nolisten tcp") to pass to the Xvfb server
+ (default: "$XVFBARGS")
+-w DELAY --wait=DELAY delay in seconds to wait for Xvfb to start
+ before running COMMAND (default:
$STARTWAIT)
EOF
- :;
}
-# find free server number by looking at .X*-lock files in /tmp
+# Find a free server number by looking at .X*-lock files in /tmp.
find_free_servernum() {
+ local i
+
i=$SERVERNUM
while [ -f /tmp/.X$i-lock ]; do
i=$(($i + 1))
done
- echo $i;
+ echo $i
}
-# parse command line
+# Parse the command line.
ARGS=$(getopt --options +ae:f:hn:lp:s:w: \
--long
auto-servernum,error-file:auth-file:,help,server-num:,listen-tcp,xauth-protocol:,server-args:,wait:
\
--name "$PROGNAME" -- "$@")
+GETOPT_STATUS=$?
-if [ $? -ne 0 ]; then
- echo "$PROGNAME: error while getting options" >&2
- exit 1
+if [ $GETOPT_STATUS -ne 0 ]; then
+ error "internal error; getopt exited with status $GETOPT_STATUS"
+ exit 6
fi
eval set -- "$ARGS"
@@ -82,9 +103,8 @@
-s|--server-args) XVFBARGS="$2"; shift ;;
-w|--wait) STARTWAIT="$2"; shift ;;
--) shift; break ;;
- *) echo "$PROGNAME: error while parsing option \"$1\"" >&2
- usage >&2
- exit 1
+ *) error "internal error; getopt permitted \"$1\" unexpectedly"
+ exit 6
;;
esac
shift
@@ -96,53 +116,54 @@
fi
if [ -z "$*" ]; then
- echo "$PROGNAME: need a command to run; aborting" >&2
+ usage "need a command to run" >&2
exit 2
fi
-if ! which xauth > /dev/null; then
- echo "$PROGNAME: xauth command not found; aborting" >&2
+if ! which xauth >/dev/null; then
+ error "xauth command not found"
exit 3
fi
-# If the user did not specify an X authorization file to use, set up a
-# temporary directory to house one.
+# If the user did not specify an X authorization file to use, set up a
temporary
+# directory to house one.
if [ -z "$AUTHFILE" ]; then
XVFB_RUN_TMPDIR="${TMPDIR:-/tmp}/$PROGNAME.$$"
if ! mkdir -p -m 700 "$XVFB_RUN_TMPDIR"; then
- echo "$PROGNAME: temporary directory $XVFB_RUN_TMPDIR already exists;"
- "aborting" >&2
+ error "temporary directory $XVFB_RUN_TMPDIR already exists"
exit 4
fi
AUTHFILE=$(tempfile -n "$XVFB_RUN_TMPDIR/Xauthority")
fi
-# start Xvfb
+# Start Xvfb.
MCOOKIE=$(mcookie)
-XAUTHORITY=$AUTHFILE xauth add :$SERVERNUM $XAUTHPROTO $MCOOKIE > $ERRORFILE
2>&1
-XAUTHORITY=$AUTHFILE Xvfb :$SERVERNUM $XVFBARGS $LISTENTCP > $ERRORFILE 2>&1 &
+XAUTHORITY=$AUTHFILE xauth add ":$SERVERNUM" "$XAUTHPROTO" "$MCOOKIE" \
+ >"$ERRORFILE" 2>&1
+XAUTHORITY=$AUTHFILE Xvfb ":$SERVERNUM" "$XVFBARGS" "$LISTENTCP" >"$ERRORFILE"
\
+ 2>&1 &
XVFBPID=$!
-sleep $STARTWAIT
+sleep "$STARTWAIT"
-# start the command and save its exit status
+# Start the command and save its exit status.
set +e
DISPLAY=:$SERVERNUM XAUTHORITY=$AUTHFILE "$@" 2>&1
RETVAL=$?
set -e
-# kill Xvfb now that the command has exited
+# Kill Xvfb now that the command has exited.
kill $XVFBPID
-# clean up
-XAUTHORITY=$AUTHFILE xauth remove :$SERVERNUM > $ERRORFILE 2>&1
+# Clean up.
+XAUTHORITY=$AUTHFILE xauth remove ":$SERVERNUM" >"$ERRORFILE" 2>&1
if [ -n "$XVFB_RUN_TMPDIR" ]; then
if ! rm -r "$XVFB_RUN_TMPDIR"; then
- echo "$PROGNAME: error while cleaning up temporary directory" >&2
+ error "problem while cleaning up temporary directory"
exit 5
fi
fi
-# return the executed command's exit status
+# Return the executed command's exit status.
exit $RETVAL
-# vim:set ai et sts=4 sw=4 tw=0:
+# vim:set ai et sts=4 sw=4 tw=80:
Property changes on: trunk/debian/local/xvfb-run
___________________________________________________________________
Name: svn:executable
+ *
Name: svn:keywords
+ Id
Modified: trunk/debian/local/xvfb-run.1
===================================================================
--- trunk/debian/local/xvfb-run.1 2004-11-12 06:00:26 UTC (rev 2026)
+++ trunk/debian/local/xvfb-run.1 2004-11-16 14:54:16 UTC (rev 2027)
@@ -25,7 +25,7 @@
\\$2 \(laURL: \\$1 \(ra\\$3
..
.if \n[.g] .mso www.tmac
-.TH xvfb\-run 1 "2004\-10\-31" "Debian Project"
+.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
@@ -68,7 +68,7 @@
one to use).
.B xvfb\-run
then exits with the exit status of
-.IR command.
+.IR command .
.PP
.B xvfb\-run
requires the
@@ -165,6 +165,14 @@
The default is 3.
.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
@@ -201,9 +209,16 @@
.B xvfb\-run
uses its exit status as well as output to standard error to communicate
diagnostics.
+The exit status of \(oq1\(cq is not used, and should be interpreted as failure
+of the specified command.
.TP
-1
-The command\-line options could not be processed.
+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
2
No command to run was specified.
@@ -212,6 +227,20 @@
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
