Man Linux: Main Page and Category List

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
                 seconds, minutes, 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)

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.