sys/man/8/qer

   1 .TH QER 8
   2 .SH NAME
   3 qer, runq \- queue management for spooled files
   4 .SH SYNOPSIS
   5 .B qer
   6 [
   7 .B -q
   8 .I subdir
   9 ]
  10 [
  11 .B -f
  12 .I file
  13 ]
  14 .I root tag reply args
  15 .br
  16 .B runq
  17 [
  18 .B -adER
  19 ]
  20 [
  21 .B -f
  22 .I file
  23 ]
  24 [
  25 .B -q
  26 .I subdir
  27 ]
  28 [
  29 .B -t
  30 .I time
  31 ]
  32 [
  33 .B -r
  34 .I nfiles
  35 ]
  36 [
  37 .B -n
  38 .I njobs
  39 ]
  40 .I root cmd
  41 .SH DESCRIPTION
  42 .I Qer
  43 creates a control and a data file in a queue directory.
  44 The control file contents consist of the
  45 .IR tag ,
  46 .IR reply ,
  47 and
  48 .I args
  49 separated by spaces.
  50 The data file contains the standard input to
  51 .IR qer .
  52 The files are created in the directory
  53 .IR root / subdi
  54 The names of the control and data files differ only
  55 in the first character which is `C' and `D' respectively.
  56 .IR Mktemp (2)
  57 is used to create the actual names of the control and
  58 data file.
  59 .P
  60 Some commands, such as
  61 .I fax
  62 (see
  63 .IR telco (4)),
  64 must queue more files than just the data file.
  65 Each
  66 .I file
  67 following a
  68 .B \-f
  69 flag is copied into the queue directory.  The names
  70 of the copies differ from the name of the data file
  71 only in the first character.  The first one
  72 starts with 'F', the second 'G', etc.
  73 .P
  74 Qer takes the following arguments:
  75 .TP
  76 .B -q subdir
  77 Specifies the queue subdirectory to use. If
  78 unspecified, the contents of
  79 .B /dev/user
  80 are used.
  81 .TP
  82 .B -f file
  83 Specifies the files to copy into the queue
  84 directory, in the manner described above.
  85 .P
  86 .I Runq
  87 processes the files queued by
  88 .IR qer .
  89 .I Runq
  90 processes all requests in the directory
  91 .IR root / subdir ,
  92 where
  93 .I subdir
  94 is the argument to
  95 .B -q
  96 if present, else the contents of
  97 .BR /dev/user .
  98 Each request is processed by executing the command
  99 .I cmd
 100 with the contents of the control file as its arguments,
 101 the contents of the data file as its standard input, and
 102 standard error appended to the error file
 103 .BR E.XXXXXX .
 104 .P
 105 The action taken by
 106 .I runq
 107 depends on the return status of
 108 .IR cmd .
 109 If
 110 .I cmd
 111 returns a null status, the processing is assumed successful and the
 112 control, data, and error files are removed.
 113 If
 114 .I cmd
 115 returns an error status containing the word
 116 .LR Retry ,
 117 the files are left to be reprocessed at a later time.
 118 For any other status, an error message is mailed
 119 to the requester and the files are removed.
 120 .I Runq
 121 uses the
 122 .I reply
 123 field in the control file as
 124 a mail address to which to send an error notification.
 125 The notification contains the contents of the control
 126 file to identify the failed request.
 127 .P
 128 To avoid reprocessing files too often, the following algorithm is used:
 129 a data file younger than one hour will not be processed if its
 130 error file exists and was last modified within the preceding 10 minutes.
 131 A data file older than one hour will not be processed if its error
 132 file exists and was last modified within the preceding hour.
 133 .PP
 134 The following flags are accepted by runq:
 135 .TP
 136 .B -a
 137 Causes runq to process all user directories in sequence, instead
 138 of only the directory of the current user.
 139 .TP
 140 .B -E
 141 Causes all files to be reprocessed regardless of
 142 the file times.
 143 .TP
 144 .B -R
 145 Instructs
 146 .I runq
 147 never to give up on a failed queue job, instead leaving
 148 it in the queue to be retried.
 149 .TP
 150 .B -d
 151 Causes debugging output on standard error
 152 describing the progress through the queues.
 153 .TP
 154 .B -t
 155 Specifies the number of hours
 156 that retries will continue after a send
 157 failure.  The default is 48 hours.
 158 .TP
 159 .BR -r
 160 Limits the number of files that are processed in a single pass of a queue.
 161 .I Runq
 162 accumulates the entire directory containing a queue before processing any
 163 files.  When a queue contains many files and the system does not
 164 have enough memory,
 165 .I runq
 166 exits without making progress.  This flag forces
 167 .I runq
 168 to process the directory in chunks, allowing the queue to
 169 be drained incrementally.  It is most useful in combination with the
 170 .I -q
 171 flag.
 172 .TP
 173 .B -n
 174 Specifies the number of queued jobs that are processed
 175 in parallel from the queue; the default is 1.
 176 This is useful for a large queue to be processed with a bounded
 177 amount of parallelism.
 178 .PP
 179 .I Runq
 180 is often called from
 181 .IR cron (8)
 182 by an entry such as
 183 .IP
 184 .EX
 185 0,10,20,30,40,50 * * * * kremvax
 186         /bin/upas/runq -a /mail/queue /mail/lib/remotemail
 187 .EE
 188 .LP
 189 The entry must be a single line; it is folded here only so it fits on the page.
 190 .SH FILES
 191 .TF \fIroot\fP/\fIuser\fP/[F-Z].XXXXXX
 192 .TP
 193 .B \fIroot\fP/\fIuser\fP
 194 queue directory for
 195 .I user
 196 .TP
 197 .B \fIroot\fP/\fIuser\fP/D.XXXXXX
 198 data file
 199 .TP
 200 .B \fIroot\fP/\fIuser\fP/C.XXXXXX
 201 control file
 202 .TP
 203 .B \fIroot\fP/\fIuser\fP/E.XXXXXX
 204 error file
 205 .TP
 206 .B \fIroot\fP/\fIuser\fP/[F-Z].XXXXXX
 207 secondary data files
 208 .SH SOURCE
 209 .B /sys/src/cmd/upas/q
 210 .SH "SEE ALSO"
 211 .IR mail (1)