| .\" |
| .\" $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. |