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