qer 4.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226
  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 -adsE
  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 is
  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 -d
  144. option causes debugging output on standard error
  145. describing the progress through the queues.
  146. .P
  147. The
  148. .B -t
  149. flags specifies the number of hours
  150. that retries will continue after a send
  151. failure. The default is 48 hours.
  152. .P
  153. The
  154. .BR -r
  155. flag limits the number of files that are processed in a single pass of a queue.
  156. .I Runq
  157. accumulates the entire directory containing a queue before processing any
  158. files. When a queue contains many files and the system does not
  159. have enough memory,
  160. .I runq
  161. exits without making progress. This flag forces
  162. .I runq
  163. to process the directory in chunks, allowing the queue to
  164. be drained incrementally. It is most useful in combination with the
  165. .I -q
  166. flag.
  167. .P
  168. The
  169. .BR -s ,
  170. .BR -n ,
  171. and
  172. .B -l
  173. flags are only meaningful with the
  174. .B -a
  175. flag. They control amount of parallelism that
  176. is used when sweeping all of the queues. The argument following the
  177. .B -n
  178. flag specifies the number of queues that are swept
  179. in parallel; the default is 50. The argument following the
  180. .B -l
  181. flag specifies the total number of queues that are being swept.
  182. By default, there is no limit. The number of active sweeps
  183. is cumulative over all active executions of
  184. .IR runq .
  185. The
  186. .B -s
  187. flag forces each queue directory to be processed by exactly
  188. one instance of
  189. .IR runq .
  190. This is useful on systems that connect to slow
  191. external systems and prevents all the queue sweeps from
  192. piling up trying to process a few slow systems.
  193. .PP
  194. .I Runq
  195. is often called from
  196. .IR cron (8)
  197. by an entry such as
  198. .IP
  199. .EX
  200. 0,10,20,30,40,50 * * * * kremvax
  201. runq -a /mail/queue /mail/lib/remotemail
  202. .EE
  203. .LP
  204. The entry must be a single line; it is folded here only so it fits on the page.
  205. .SH FILES
  206. .TF \fIroot\fP/\fIuser\fP/[F-Z].XXXXXX
  207. .TP
  208. .B \fIroot\fP/\fIuser\fP
  209. queue directory for
  210. .I user
  211. .TP
  212. .B \fIroot\fP/\fIuser\fP/D.XXXXXX
  213. data file
  214. .TP
  215. .B \fIroot\fP/\fIuser\fP/C.XXXXXX
  216. control file
  217. .TP
  218. .B \fIroot\fP/\fIuser\fP/E.XXXXXX
  219. error file
  220. .TP
  221. .B \fIroot\fP/\fIuser\fP/[F-Z].XXXXXX
  222. secondary data files
  223. .SH SOURCE
  224. .B /sys/src/cmd/upas/q
  225. .SH "SEE ALSO"
  226. .IR mail (1)