Learn how easy it is to sync an existing GitHub or Google Code repo to a SourceForge project! See Demo

Close

Diff of /doc/man1/pan.1 [000000] .. [f307d5] Maximize Restore

  Switch to side-by-side view

--- a
+++ b/doc/man1/pan.1
@@ -0,0 +1,226 @@
+.\"
+.\" $Id: pan.1,v 1.1 2000/09/14 21:54:44 nstraz Exp $
+.\"
+.\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
+.\" 
+.\" This program is free software; you can redistribute it and/or modify it
+.\" under the terms of version 2 of the GNU General Public License as
+.\" published by the Free Software Foundation.
+.\" 
+.\" This program is distributed in the hope that it would be useful, but
+.\" WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.\" 
+.\" Further, this software is distributed without any warranty that it is
+.\" free of the rightful claim of any third person regarding infringement
+.\" or the like.  Any license provided herein, whether implied or
+.\" otherwise, applies only to this software file.  Patent licenses, if
+.\" any, provided herein do not apply to combinations of this program with
+.\" other software, or any other product whatsoever.
+.\" 
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write the Free Software Foundation, Inc., 59
+.\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
+.\" 
+.\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
+.\" Mountain View, CA  94043, or:
+.\" 
+.\" http://www.sgi.com 
+.\" 
+.\" For further information regarding this notice, see: 
+.\" 
+.\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
+.TH PAN 1 "14 Sep 2000" "LTP" "Linux Test Project"
+.SH NAME
+pan \- A light-weight driver to run tests and clean up their pgrps
+.SH SYNOPSIS
+\fBpan -n tagname [-SyAeh] [-s \fIstarts\fB] [\fI-x nactive\fB] [\fI-l logfile\fB] [\fI-a active-file\fB] [\fI-f command-file\fB] [\fI-d debug-level\fB] [cmd]
+.SH DESCRIPTION
+
+Pan will run a command, as specified on the commandline, or collection of
+commands from a command-file.  By default pan runs one command, choosing it at
+random from the whole set of commands available to it.  The pan's name in the
+active file is specified by the tagname.  When a command terminates pan will
+kill any orphans that may have been left behind in its pgrp.  If pan is
+signaled it will kill any active commands and, again, clean up any orphans.
+
+Pan uses the signal ratchet found in other zoo tools.  The first time pan is
+signaled it sends a SIGTERM to the active pgrps; the second time it sends
+SIGHUP; the third time a SIGINT; after that it always sends SIGKILL.
+
+Pan will not terminate until all the active commands and everything in their
+pgrps is dead.  It will loop around at 5 second intervals, triggering its own
+signal ratchet, until it succeeds in killing the pgrps.
+
+When the pan starts up it places its own tagname and commandline in the active
+file and begins scheduling commands.  After a command is started pan puts an
+entry for it into the active file with its indicated tagname.  If the command
+was specified on the command line, rather than in the command-file, then its
+tagname will be "cmdln".  When a process terminates pan frees the active file
+entry.  If a command terminates and leaves an orphaned pgrp then pan will put
+an entry into the active file called "panorphan" which will be removed only
+when the orphaned pgrp is cleaned up.  Before pan exits it will ensure that
+all orphaned pgrps are dead (see above) and then it will remove its own
+tagname from the active file.
+
+The command-file is a file containing tag/command pairs.  Each line in the
+file begins with a tag identifying the command, followed by white space, and
+then the command and its arguments.  A line beginning with the # character is
+a comment.  Pan recognizes the token "%f" in a command's arguments and
+replaces it with a unique identifier--add this to filename arguments to
+prevent two instances of the command from interfering with each other.
+
+When pan receives a SIGUSR2 it stops scheduling new tests and waits for the
+active tests to terminate.  If the \fB-y\fP option was used then it will begin
+scheduling again, otherwise it will exit.  It does not propagate the SIGUSR2.
+
+.TP 1i
+\fB-A\fP
+The all-stop flag.  If any command exits non-zero pan will shutdown its
+scheduler and signal any active pgrps.  The pan will exit non-zero after
+everything is shut down.  By default pan ignores command exit statuses.
+The \fI-e\fP option is implied when this option is used.
+.TP 1i
+\fB-a \fIactive_file\fB
+A file containing the tagnames, pids, and commands being run.  If this is
+not specified then the ZOO environment variable will be read for the name
+of a directory where the active file will be placed, and in this case the
+active file's name will be "active".  A single active file may be shared
+by any number of Zoo tools.
+.TP 1i
+\fB-d \fIdebug-level\fB
+See the source for settings.
+.TP 1i
+\fB-e\fP
+Pan will exit non-zero if any of its commands exited non-zero.  By default
+pan ignores command exit statuses.
+.TP 1i
+\fB-h\fP
+Print some simple help.
+.TP 1i
+\fB-l \fIlogfile\fB
+Name of a log file to be used to store exit information for each of the
+commands (tags) that are run.  This log file may not be shared with other Zoo
+tools or other pan processes.
+.TP 1i
+\fB-n \fItagname\fB
+The tagname by which this pan process will be known by the zoo tools.  This
+is a required argument.
+.TP 1i
+\fB-S\fP
+Causes pan to run commands (tags) sequentially, as they are listed in the
+command-file.  By default it chooses tags randomly.  If a command is specified
+on the commandline and a command-file is also specified, then the commandline
+tag will be the last command.  If this is specified and \fI-s\fP is not
+specified then the default setting for \fI-s\fP is equal to the total number
+of commands.
+.TP 1i
+\fB-s \fIstarts\fB
+Indicates the number of commands (tags) that should be run before terminating.
+Set this to zero to run forever.  By default this is set to 1 (but see
+\fI-S\fP for an exception).  If this is specified and is less than the value
+specified for \fI-x\fP then it is bumped up to be equal to the value of
+\fI-x\fP (in other words, \fI-x\fP is always satisfied).
+.TP 1i
+\fB-x \fInactive\fB
+Indicates the number of commands (tags) that should be kept active at any one
+time.  If this is greater than 1 then it is possible to have multiple
+instances of the same tag active at once.  By default this is 1.
+.TP 1i
+\fB-y\fP
+Causes the pan scheduler to go idle if a signal is received or if a command
+exits non-zero.  All active commands and their pgrps will be killed.  After
+everything is dead the scheduler will restart again where it left off.  If the
+signal is SIGUSR1 then pan will behave as if \fI-y\fP had not been specified.
+
+.in -1i
+
+.SH EXAMPLES
+
+In practice, the ZOO environment variable is generally prefered over the
+\fI-a\fP option.  All examples assume this is being set.
+
+The following creates a pan named "ex1" with an active file in /tmp/active.
+It runs the command "echo hello", keeping 3 copies running at all times,
+running 10 copies before terminating.
+
+$ export ZOO=/tmp
+.br
+$ pan -n ex1 -s 10 -x 3 echo hello
+
+The next example will use this command file.  Call this /tmp/cmds1.
+.br
+----------cut------
+.br
+fido    ls /bin
+.br
+rover   echo hello wally
+.br
+gidget  sleep 2
+.br
+lassie  ls /etc
+.br
+----------cut------
+.br
+
+Using the above command file, /tmp/cmds1, run one command at a time,
+sequentially, running each command only once.  If one command should fail then
+terminate immediately.  An exit log is kept for all the commands.
+
+$ pan -n ex3 -S -A -f /tmp/cmds1 -l ex3.log
+
+
+.SH LAYERING
+
+Pan is often used in layers.  This section extends the above examples to show
+how this is done.
+
+The next example will use this command file.  Call this /tmp/cmds2.  Note that
+the embedded pans inside this file have exit logs, and that %f is used to give
+each pan a unique log file name.
+.br
+----------cut------
+.br
+larry  pan -n ex4b -s10 -A -l ex4_%f.log echo hello
+.br
+curly  pan -n ex4c -S -A -f /tmp/cmds1 -l ex4_%f.log
+.br
+moe    echo done here
+.br
+----------cut------
+.br
+
+The following will run commands from the command file, keeping two at a time
+running, choosing them sequentially, and terminating if any of them exits
+non-zero.
+
+$ pan -n ex4 -x2 -A -S -f /tmp/cmds2
+
+Now run the commands in /tmp/cmds2, but this time we want to recover if one of
+the commands should exit non-zero.  In this example it is possible for the
+"larry" or "curly" tags to exit non-zero.  When this happens the pan will kill
+all active tags, making sure both larry and curly are dead, and then will
+continue scheduling--ensuring that our "done here" message comes out no matter
+what.
+
+$ pan -n ex5 -x2 -A -S -y -f /tmp/cmds2
+
+.SH ENVIRONMENT
+.TP
+ZOO
+If set, should name the directory where the active file should be placed.
+This is ignored if \fI-a\fP is specified.
+
+.SH FILES
+.TP
+active
+Default name of active file if \fI-a\fP is not specified.  This is prefixed
+by the directory name found in the ZOO environment variable.
+
+.SH "SEE ALSO"
+Zoo tools - bump(1)
+
+.SH DIAGNOSTICS
+By default it exits zero unless signaled, regardless of the exit status of any
+of the commands it is running.  If \fI-A\fP or \fI-e\fP are specified it exits non-zero if
+it is signaled or if any of the commands it is running should exit non-zero.