You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
263 lines
11 KiB
263 lines
11 KiB
.\"
|
|
.\" $Id: ltp-pan.1,v 1.1 2009/05/19 09:39:11 subrata_modak 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.,
|
|
.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 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 "21 Jan 2011" "LTP" "Linux Test Project"
|
|
.SH NAME
|
|
ltp-pan \- A light-weight driver to run tests and clean up their pgrps
|
|
.SH SYNOPSIS
|
|
\fBltp-pan -n tagname [-SyAehp] [-t #s|m|h|d \fItime\fB] [-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] [\fI-o output-file\fB] [\fI-O buffer_directory\fB] [\fI-r report_type\fB] [\fI-C fail-command-file\fB] [cmd]
|
|
.SH DESCRIPTION
|
|
|
|
Pan will run a command, as specified on the commandline, or collection of
|
|
commands from a command-file. By default ltp-pan runs one command, choosing it at
|
|
random from the whole set of commands available to it. The ltp-pan's name in the
|
|
active file is specified by the tagname. When a command terminates ltp-pan will
|
|
kill any orphans that may have been left behind in its pgrp. If ltp-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 ltp-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 ltp-pan starts up it places its own tagname and commandline in the active
|
|
file and begins scheduling commands. After a command is started ltp-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 ltp-pan frees the active file
|
|
entry. If a command terminates and leaves an orphaned pgrp then ltp-pan will put
|
|
an entry into the active file called "panorphan" which will be removed only
|
|
when the orphaned pgrp is cleaned up. Before ltp-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 ltp-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 ltp-pan will shutdown its
|
|
scheduler and signal any active pgrps. The ltp-pan will exit non-zero after
|
|
everything is shut down. By default ltp-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-C \fIfail-command-file\fB
|
|
The file to which all failed test commands will be saved. You can use it later with \fI-f\fP option if you want to run only the failed test cases.
|
|
.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
|
|
ltp-pan ignores command exit statuses.
|
|
.TP 1i
|
|
\fB-f \fIcommand-file\fB
|
|
The file that has a collection of commands that ltp-pan will execute.
|
|
.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 ltp-pan processes.
|
|
.TP 1i
|
|
\fB-n \fItagname\fB
|
|
The tagname by which this ltp-pan process will be known by the zoo tools. This
|
|
is a required argument.
|
|
.TP 1i
|
|
\fB-o \fIoutput_file\fB
|
|
The file to which all test output will be saved. Normally all test output is sent to standard output. This includes each test's standard output and standard error.
|
|
.TP 1i
|
|
\fB-O \fIbuffer_directory\fB
|
|
A directory where ltp-pan can place temporary files to capture test output. This will prevent output from several tests mixing together in the output file.
|
|
.TP 1i
|
|
\fB-p\fP
|
|
Enables printing results in human readable format.
|
|
.TP 1i
|
|
\fB-r \fIreport_type\fB
|
|
This controls the type of output that ltp-pan will produce. Supported formats are \fIrts\fP and \fInone\fP. The default is \fIrts\fP.
|
|
.TP 1i
|
|
\fB-S\fP
|
|
Causes ltp-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-t #s|m|h|d \fItime\fB
|
|
Indicates the length that ltp-pan should run tests. By default this is not set. If specified,
|
|
the \fI-s\fP flag is automatically set to 0 (infinite). Presumably, you want as many
|
|
tests ran during this timeframe. Duration is measured in \fIs\fPeconds, \fIm\fPinutes,
|
|
\fIh\fPours, or \fId\fPays.
|
|
.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 ltp-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 ltp-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 ltp-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
|
|
$ ltp-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.
|
|
|
|
$ ltp-pan -n ex3 -S -A -f /tmp/cmds1 -l ex3.log
|
|
|
|
Here is just a simple stress case. In this case the test will run for 24 hours,
|
|
printing the output as a human readable format, with the test output at /tmp/output-file
|
|
and all failed test commands (if you have any) at /tmp/fail-command-file.
|
|
|
|
$ ltp-pan -n stress -e -p -q -S -t 24h -a stress -l logfile -f command-file \
|
|
-o /tmp/output-file -C /tmp/fail-command-file
|
|
|
|
.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 ltp-pans inside this file have exit logs, and that %f is used to give
|
|
each ltp-pan a unique log file name.
|
|
.br
|
|
----------cut------
|
|
.br
|
|
larry ltp-pan -n ex4b -s10 -A -l ex4_%f.log echo hello
|
|
.br
|
|
curly ltp-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.
|
|
|
|
$ ltp-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 ltp-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.
|
|
|
|
$ ltp-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.
|
|
.TP
|
|
PAN_STOP_FILE
|
|
The creation of this file in the defined \fITMP\fP directory will cause ltp-pan to
|
|
execute one more loop and stop. This is useful when testing needs to be stopped
|
|
before its scheduled stop time (\fI-t\fP). By doing a 'touch' on this file, testing
|
|
is ended, i.e. touch /tmp/runalltests-2345/PAN_STOP_FILE
|
|
|
|
.SH "SEE ALSO"
|
|
Zoo tools - ltp-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.
|