--- name: "ltp-pan" section: "1" platform: "linux" package: "ltp-tools" version: "20091231+dfsg-1" release: "Debian 6.0 (Squeeze)" platforms: ["linux"] url: "https://new.carta.tech/ltp-pan" --- # ltp-pan(1) A light-weight driver to run tests and clean up their pgrps ## NAME ltp-pan - A light-weight driver to run tests and clean up their pgrps ## SYNOPSIS **ltp-pan -n tagname \[-SyAehp\] \[-t #s\|m\|h\|d** *time***\] \[-s** *starts***\] \[***-x nactive***\] \[***-l logfile***\] \[***-a active-file***\] \[***-f command-file***\] \[***-d debug-level***\] \[***-o output-file***\] \[***-O buffer\_directory***\] \[***-r report\_type***\] \[***-C fail-command-file***\] \[cmd\]** ## 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 -y option was used then it will begin** **scheduling again, otherwise it will exit. It does not propagate the SIGUSR2.** - **-A** **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** *-e* **option is implied when this option is used.** - **-a** *active\_file* **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.** - **-C** *fail-command-file* **The file to which all failed test commands will be saved. You can use it later with** *-f* **option if you want to run only the failed test cases.** - **-d** *debug-level* **See the source for settings.** - **-e** **Pan will exit non-zero if any of its commands exited non-zero. By default** **ltp-pan ignores command exit statuses.** - **-f** *command-file* **The file that has a collection of commands that ltp-pan will execute.** - **-h** **Print some simple help.** - **-l** *logfile* **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.** - **-n** *tagname* **The tagname by which this ltp-pan process will be known by the zoo tools. This** **is a required argument.** - **-o** *output\_file* **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.** - **-O** *buffer\_directory* **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.** - **-p** **Enables printing results in human readable format.** - **-r** *report\_type* **This controls the type of output that ltp-pan will produce. Supported formats are** *rts* **and** *none***. The default is** *rts***.** - **-S** **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** *-s* **is not** **specified then the default setting for** *-s* **is equal to the total number** **of commands.** - **-s** *starts* **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** *-S* **for an exception). If this is specified and is less than the value** **specified for** *-x* **then it is bumped up to be equal to the value of** *-x* **(in other words,** *-x* **is always satisfied).** - **-t #s\|m\|h\|d** *time* **Indicates the length that ltp-pan should run tests. By default this is not set. If specified,** **the** *-s* **flag is automatically set to 0 (infinite). Presumably, you want as many** **tests ran during this timeframe. Duration is measured in** *s***econds,** *m***inutes,** *hPours,OR dPays.* - **-x** *nactive* **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.** - **-y** **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** *-y* **had not been specified.** ## EXAMPLES **In practice, the ZOO environment variable is generally prefered over the** *-a* **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**\ **$ ltp-pan -n ex1 -s 10 -x 3 echo hello** **The next example will use this command file. Call this /tmp/cmds1.**\ **----------cut------**\ **fido ls /bin**\ **rover echo hello wally**\ **gidget sleep 2**\ **lassie ls /etc**\ **----------cut------**\ **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** ## 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.**\ **----------cut------**\ **larry ltp-pan -n ex4b -s10 -A -l ex4\_%f.log echo hello**\ **curly ltp-pan -n ex4c -S -A -f /tmp/cmds1 -l ex4\_%f.log**\ **moe echo done here**\ **----------cut------**\ **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** ## ENVIRONMENT - **ZOO** **If set, should name the directory where the active file should be placed.** **This is ignored if** *-a* **is specified.** ## FILES - **active** **Default name of active file if** *-a* **is not specified. This is prefixed** **by the directory name found in the ZOO environment variable.** - **PAN\_STOP\_FILE** **The creation of this file in the defined** *TMP* **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 (***-t***). By doing a 'touch' on this file, testing** **is ended, i.e. touch /tmp/runalltests-2345/PAN\_STOP\_FILE** ## SEE ALSO **Zoo tools - [ltp-bump(1)](/ltp-bump/1.md)** ## DIAGNOSTICS **By default it exits zero unless signaled, regardless of the exit status of any** **of the commands it is running. If** *-A* **or** *-e* **are specified it exits non-zero if** **it is signaled or if any of the commands it is running should exit non-zero.**