runtrap(8)                         runtools                         runtrap(8)



NAME
       runtrap - run a program with a signal trapper

SYNOPSIS
       runtrap [-hV] id trapper program [ args ...  ]

DESCRIPTION
       runtrap  starts program with any args and monitors it as a long-running
       process.  If runtrap notices that program terminates, it restarts it.

       Whenever runtrap itself receives any signal it can  catch,  it  invokes
       the argument given by trapper in this form:

              trapper ``trap'' id pid signum signame

       Where:

              trapper

                     The  name of an executable specified in the trapper argu-
                     ment on the command-line.

              ``trap''

                     The verbatim string ``trap''.

              id

                     A simple string specified in the id argument on the  com-
                     mand-line.

              pid

                     The process ID of the program that runtrap is monitoring.

              signum

                     The numeric decimal representation of the signal received
                     by runtrap.

              signame

                     The symbolic name for the signal received by runtrap.

       Presumably  trapper is a short-running program designed to perform some
       special handling of signals destined for program.  After invoking trap-
       per,  runtrap waits for it to complete and then resumes monitoring pro-
       gram.

       If runtrap receives a SIGTERM, it flags itself to terminate.   It  then
       invokes  trapper  as above with SIGTERM arguments.  When program termi-
       nates, runtrap itself then exits normally.

OPTIONS
       -h     Help.  Print a brief usage message to stderr and exit.

       -V     Version.  Print the version number to stderr and exit.

EXAMPLES
       runtrap is designed for use in perpetrate(5)  runscripts  for  services
       that  need  special  signal  handling.   The example below shows how an
       rc.main runscript may be multiplexed to handle ``trap'' targets:

              #!/bin/sh
              exec 2>&1

              TARGET=${1}
              SVNAME=${2}

              start() {
                echo "starting ${SVNAME} ..."
                exec runtrap ${SVNAME} ./rc.main /usr/sbin/foo -f
              }

              reset() {
                echo "resetting ${SVNAME} ..."
                #...
              }

              trap() {
                SVPID=${3}
                SIGNUM=${4}
                SIGNAME=${5}
                echo "trapping ${SVNAME} for signal ${SIGNAME} ..."
                kill -${SIGNUM} ${SVPID}
              }

              eval ${TARGET} "$@"

              ### EOF

AUTHOR
       Wayne Marshall, http://b0llix.net/perp/

SEE ALSO
       runtools_intro(8), runargs(8), runargv0(8), runchoom(8),  rundetach(8),
       rundeux(8),    runenv(8),    runfile(8),    runlimit(8),    runlock(8),
       runpause(8),   runsession(8),    runtool(8),    runuid(8),    perpd(8),
       perpetrate(5)



runtools-2.07                    January 2013                       runtrap(8)