doc/man1/ltp-pan.1

   1 .\"
   2 .\" $Id: ltp-pan.1,v 1.1 2009/05/19 09:39:11 subrata_modak Exp $
   3 .\"
   4 .\" Copyright (c) 2000 Silicon Graphics, Inc.  All Rights Reserved.
   5 .\"
   6 .\" This program is free software; you can redistribute it and/or modify it
   7 .\" under the terms of version 2 of the GNU General Public License as
   8 .\" published by the Free Software Foundation.
   9 .\"
  10 .\" This program is distributed in the hope that it would be useful, but
  11 .\" WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  13 .\"
  14 .\" Further, this software is distributed without any warranty that it is
  15 .\" free of the rightful claim of any third person regarding infringement
  16 .\" or the like.  Any license provided herein, whether implied or
  17 .\" otherwise, applies only to this software file.  Patent licenses, if
  18 .\" any, provided herein do not apply to combinations of this program with
  19 .\" other software, or any other product whatsoever.
  20 .\"
  21 .\" You should have received a copy of the GNU General Public License along
  22 .\" with this program; if not, write the Free Software Foundation, Inc., 59
  23 .\" Temple Place - Suite 330, Boston MA 02111-1307, USA.
  24 .\"
  25 .\" Contact information: Silicon Graphics, Inc., 1600 Amphitheatre Pkwy,
  26 .\" Mountain View, CA  94043, or:
  27 .\"
  28 .\" http://www.sgi.com
  29 .\"
  30 .\" For further information regarding this notice, see:
  31 .\"
  32 .\" http://oss.sgi.com/projects/GenInfo/NoticeExplan/
  33 .TH PAN 1ltp "19 Feb 2002" "LTP" "Linux Test Project"
  34 .SH NAME
  35 ltp-pan \- A light-weight driver to run tests and clean up their pgrps
  36 .SH SYNOPSIS
  37 \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]
  38 .SH DESCRIPTION
  39
  40 Pan will run a command, as specified on the commandline, or collection of
  41 commands from a command-file.  By default ltp-pan runs one command, choosing it at
  42 random from the whole set of commands available to it.  The ltp-pan's name in the
  43 active file is specified by the tagname.  When a command terminates ltp-pan will
  44 kill any orphans that may have been left behind in its pgrp.  If ltp-pan is
  45 signaled it will kill any active commands and, again, clean up any orphans.
  46
  47 Pan uses the signal ratchet found in other zoo tools.  The first time ltp-pan is
  48 signaled it sends a SIGTERM to the active pgrps; the second time it sends
  49 SIGHUP; the third time a SIGINT; after that it always sends SIGKILL.
  50
  51 Pan will not terminate until all the active commands and everything in their
  52 pgrps is dead.  It will loop around at 5 second intervals, triggering its own
  53 signal ratchet, until it succeeds in killing the pgrps.
  54
  55 When the ltp-pan starts up it places its own tagname and commandline in the active
  56 file and begins scheduling commands.  After a command is started ltp-pan puts an
  57 entry for it into the active file with its indicated tagname.  If the command
  58 was specified on the command line, rather than in the command-file, then its
  59 tagname will be "cmdln".  When a process terminates ltp-pan frees the active file
  60 entry.  If a command terminates and leaves an orphaned pgrp then ltp-pan will put
  61 an entry into the active file called "panorphan" which will be removed only
  62 when the orphaned pgrp is cleaned up.  Before ltp-pan exits it will ensure that
  63 all orphaned pgrps are dead (see above) and then it will remove its own
  64 tagname from the active file.
  65
  66 The command-file is a file containing tag/command pairs.  Each line in the
  67 file begins with a tag identifying the command, followed by white space, and
  68 then the command and its arguments.  A line beginning with the # character is
  69 a comment.  Pan recognizes the token "%f" in a command's arguments and
  70 replaces it with a unique identifier--add this to filename arguments to
  71 prevent two instances of the command from interfering with each other.
  72
  73 When ltp-pan receives a SIGUSR2 it stops scheduling new tests and waits for the
  74 active tests to terminate.  If the \fB-y\fP option was used then it will begin
  75 scheduling again, otherwise it will exit.  It does not propagate the SIGUSR2.
  76
  77 .TP 1i
  78 \fB-A\fP
  79 The all-stop flag.  If any command exits non-zero ltp-pan will shutdown its
  80 scheduler and signal any active pgrps.  The ltp-pan will exit non-zero after
  81 everything is shut down.  By default ltp-pan ignores command exit statuses.
  82 The \fI-e\fP option is implied when this option is used.
  83 .TP 1i
  84 \fB-a \fIactive_file\fB
  85 A file containing the tagnames, pids, and commands being run.  If this is
  86 not specified then the ZOO environment variable will be read for the name
  87 of a directory where the active file will be placed, and in this case the
  88 active file's name will be "active".  A single active file may be shared
  89 by any number of Zoo tools.
  90 .TP 1i
  91 \fB-C \fIfail-command-file\fB
  92 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.
  93 .TP 1i
  94 \fB-d \fIdebug-level\fB
  95 See the source for settings.
  96 .TP 1i
  97 \fB-e\fP
  98 Pan will exit non-zero if any of its commands exited non-zero.  By default
  99 ltp-pan ignores command exit statuses.
 100 .TP 1i
 101 \fB-f \fIcommand-file\fB
 102 The file that has a collection of commands that ltp-pan will execute.
 103 .TP 1i
 104 \fB-h\fP
 105 Print some simple help.
 106 .TP 1i
 107 \fB-l \fIlogfile\fB
 108 Name of a log file to be used to store exit information for each of the
 109 commands (tags) that are run.  This log file may not be shared with other Zoo
 110 tools or other ltp-pan processes.
 111 .TP 1i
 112 \fB-n \fItagname\fB
 113 The tagname by which this ltp-pan process will be known by the zoo tools.  This
 114 is a required argument.
 115 .TP 1i
 116 \fB-o \fIoutput_file\fB
 117 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.
 118 .TP 1i
 119 \fB-O \fIbuffer_directory\fB
 120 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.
 121 .TP 1i
 122 \fB-p\fP
 123 Enables printing results in human readable format.
 124 .TP 1i
 125 \fB-r \fIreport_type\fB
 126 This controls the type of output that ltp-pan will produce.  Supported formats are \fIrts\fP and \fInone\fP.  The default is \fIrts\fP.
 127 .TP 1i
 128 \fB-S\fP
 129 Causes ltp-pan to run commands (tags) sequentially, as they are listed in the
 130 command-file.  By default it chooses tags randomly.  If a command is specified
 131 on the commandline and a command-file is also specified, then the commandline
 132 tag will be the last command.  If this is specified and \fI-s\fP is not
 133 specified then the default setting for \fI-s\fP is equal to the total number
 134 of commands.
 135 .TP 1i
 136 \fB-s \fIstarts\fB
 137 Indicates the number of commands (tags) that should be run before terminating.
 138 Set this to zero to run forever.  By default this is set to 1 (but see
 139 \fI-S\fP for an exception).  If this is specified and is less than the value
 140 specified for \fI-x\fP then it is bumped up to be equal to the value of
 141 \fI-x\fP (in other words, \fI-x\fP is always satisfied).
 142 .TP 1i
 143 \fB-t #s|m|h|d \fItime\fB
 144 Indicates the length that ltp-pan should run tests. By default this is not set.  If specified,
 145 the \fI-s\fP flag is automatically set to 0 (infinite).  Presumably, you want as many
 146 tests ran during this timeframe. Duration is measured in \fIs\fPeconds, \fIm\fPinutes,
 147 \fIh\Pours,OR \fId\Pays.
 148 .TP 1i
 149 \fB-x \fInactive\fB
 150 Indicates the number of commands (tags) that should be kept active at any one
 151 time.  If this is greater than 1 then it is possible to have multiple
 152 instances of the same tag active at once.  By default this is 1.
 153 .TP 1i
 154 \fB-y\fP
 155 Causes the ltp-pan scheduler to go idle if a signal is received or if a command
 156 exits non-zero.  All active commands and their pgrps will be killed.  After
 157 everything is dead the scheduler will restart again where it left off.  If the
 158 signal is SIGUSR1 then ltp-pan will behave as if \fI-y\fP had not been specified.
 159
 160 .in -1i
 161
 162 .SH EXAMPLES
 163
 164 In practice, the ZOO environment variable is generally prefered over the
 165 \fI-a\fP option.  All examples assume this is being set.
 166
 167 The following creates a ltp-pan named "ex1" with an active file in /tmp/active.
 168 It runs the command "echo hello", keeping 3 copies running at all times,
 169 running 10 copies before terminating.
 170
 171 $ export ZOO=/tmp
 172 .br
 173 $ ltp-pan -n ex1 -s 10 -x 3 echo hello
 174
 175 The next example will use this command file.  Call this /tmp/cmds1.
 176 .br
 177 ----------cut------
 178 .br
 179 fido    ls /bin
 180 .br
 181 rover   echo hello wally
 182 .br
 183 gidget  sleep 2
 184 .br
 185 lassie  ls /etc
 186 .br
 187 ----------cut------
 188 .br
 189
 190 Using the above command file, /tmp/cmds1, run one command at a time,
 191 sequentially, running each command only once.  If one command should fail then
 192 terminate immediately.  An exit log is kept for all the commands.
 193
 194 $ ltp-pan -n ex3 -S -A -f /tmp/cmds1 -l ex3.log
 195
 196 Here is just a simple stress case. In this case the test will run for 24 hours,
 197 printing the output as a human readable format, with the test output at /tmp/output-file
 198 and all failed test commands (if you have any) at /tmp/fail-command-file.
 199
 200 $ ltp-pan -n stress -e -p -q -S -t 24h -a stress -l logfile -f command-file \
 201                 -o /tmp/output-file -C /tmp/fail-command-file
 202
 203 .SH LAYERING
 204
 205 Pan is often used in layers.  This section extends the above examples to show
 206 how this is done.
 207
 208 The next example will use this command file.  Call this /tmp/cmds2.  Note that
 209 the embedded ltp-pans inside this file have exit logs, and that %f is used to give
 210 each ltp-pan a unique log file name.
 211 .br
 212 ----------cut------
 213 .br
 214 larry  ltp-pan -n ex4b -s10 -A -l ex4_%f.log echo hello
 215 .br
 216 curly  ltp-pan -n ex4c -S -A -f /tmp/cmds1 -l ex4_%f.log
 217 .br
 218 moe    echo done here
 219 .br
 220 ----------cut------
 221 .br
 222
 223 The following will run commands from the command file, keeping two at a time
 224 running, choosing them sequentially, and terminating if any of them exits
 225 non-zero.
 226
 227 $ ltp-pan -n ex4 -x2 -A -S -f /tmp/cmds2
 228
 229 Now run the commands in /tmp/cmds2, but this time we want to recover if one of
 230 the commands should exit non-zero.  In this example it is possible for the
 231 "larry" or "curly" tags to exit non-zero.  When this happens the ltp-pan will kill
 232 all active tags, making sure both larry and curly are dead, and then will
 233 continue scheduling--ensuring that our "done here" message comes out no matter
 234 what.
 235
 236 $ ltp-pan -n ex5 -x2 -A -S -y -f /tmp/cmds2
 237
 238 .SH ENVIRONMENT
 239 .TP
 240 ZOO
 241 If set, should name the directory where the active file should be placed.
 242 This is ignored if \fI-a\fP is specified.
 243
 244 .SH FILES
 245 .TP
 246 active
 247 Default name of active file if \fI-a\fP is not specified.  This is prefixed
 248 by the directory name found in the ZOO environment variable.
 249 .TP
 250 PAN_STOP_FILE
 251 The creation of this file in the defined \fITMP\fP directory will cause ltp-pan to
 252 execute one more loop and stop.  This is useful when testing needs to be stopped
 253 before its scheduled stop time (\fI-t\fP).  By doing a 'touch' on this file, testing
 254 is ended, i.e. touch /tmp/runalltests-2345/PAN_STOP_FILE
 255
 256 .SH "SEE ALSO"
 257 Zoo tools - ltp-bump(1)
 258
 259 .SH DIAGNOSTICS
 260 By default it exits zero unless signaled, regardless of the exit status of any
 261 of the commands it is running.  If \fI-A\fP or \fI-e\fP are specified it exits non-zero if
 262 it is signaled or if any of the commands it is running should exit non-zero.