futility(1) An idiot admires complexity


     QER(8)                                                     QER(8)

     NAME
          qer, runq - queue management for spooled files

     SYNOPSIS
          qer [ -q subdir ] [ -f file ] root tag reply args
          runq [ -adER ] [ -f file ] [ -q subdir ] [ -t time ] [ -r
          nfiles ] [ -n njobs ] root cmd

     DESCRIPTION
          Qer creates a control and a data file in a queue directory.
          The control file contents consist of the tag, reply, and
          args separated by spaces.  The data file contains the stan-
          dard input to qer. The files are created in the directory
          root/subdi The names of the control and data files differ
          only in the first character which is `C' and `D' respec-
          tively.  Mktemp(2) is used to create the actual names of the
          control and data file.

          Some commands, such as fax (see telco(4)), must queue more
          files than just the data file.  Each file following a -f
          flag is copied into the queue directory.  The names of the
          copies differ from the name of the data file only in the
          first character.  The first one starts with 'F', the second
          'G', etc.

          Qer takes the following arguments:

          -q subdir
               Specifies the queue subdirectory to use. If unspeci-
               fied, the contents of /dev/user are used.

          -f file
               Specifies the files to copy into the queue directory,
               in the manner described above.

          Runq processes the files queued by qer. Runq processes all
          requests in the directory root/subdir, where subdir is the
          argument to -q if present, else the contents of /dev/user.
          Each request is processed by executing the command cmd with
          the contents of the control file as its arguments, the con-
          tents of the data file as its standard input, and standard
          error appended to the error file E.XXXXXX.

          The action taken by runq depends on the return status of
          cmd. If cmd returns a null status, the processing is assumed
          successful and the control, data, and error files are
          removed.  If cmd returns an error status containing the word
          `Retry', the files are left to be reprocessed at a later
          time.  For any other status, an error message is mailed to
          the requester and the files are removed.  Runq uses the

     QER(8)                                                     QER(8)

          reply field in the control file as a mail address to which
          to send an error notification.  The notification contains
          the contents of the control file to identify the failed
          request.

          To avoid reprocessing files too often, the following algo-
          rithm is used: a data file younger than one hour will not be
          processed if its error file exists and was last modified
          within the preceding 10 minutes.  A data file older than one
          hour will not be processed if its error file exists and was
          last modified within the preceding hour.

          The following flags are accepted by runq:

          -a   Causes runq to process all user directories in
               sequence, instead of only the directory of the current
               user.

          -E   Causes all files to be reprocessed regardless of the
               file times.

          -R   Instructs runq never to give up on a failed queue job,
               instead leaving it in the queue to be retried.

          -d   Causes debugging output on standard error describing
               the progress through the queues.

          -t   Specifies the number of hours that retries will con-
               tinue after a send failure.  The default is 48 hours.

          -r   Limits the number of files that are processed in a sin-
               gle pass of a queue.  Runq accumulates the entire
               directory containing a queue before processing any
               files.  When a queue contains many files and the system
               does not have enough memory, runq exits without making
               progress.  This flag forces runq to process the direc-
               tory in chunks, allowing the queue to be drained incre-
               mentally.  It is most useful in combination with the -q
               flag.

          -n   Specifies the number of queued jobs that are processed
               in parallel from the queue; the default is 1.  This is
               useful for a large queue to be processed with a bounded
               amount of parallelism.

          Runq is often called from cron(8) by an entry such as

               0,10,20,30,40,50 * * * * kremvax
                       /bin/upas/runq -a /mail/queue /mail/lib/remotemail

          The entry must be a single line; it is folded here only so
          it fits on the page.

     QER(8)                                                     QER(8)

     FILES
          root/user               queue directory for user
          root/user/D.XXXXXX      data file
          root/user/C.XXXXXX      control file
          root/user/E.XXXXXX      error file
          root/user/[F-Z].XXXXXX  secondary data files

     SOURCE
          /sys/src/cmd/upas/q

     SEE ALSO
          mail(1)