Annotation of src/usr.bin/at/at.1, Revision 1.22
1.22 ! millert 1: .\" $OpenBSD: at.1,v 1.21 2002/05/11 22:14:48 millert Exp $
1.4 millert 2: .\" $FreeBSD: at.man,v 1.6 1997/02/22 19:54:05 peter Exp $
3: .Dd April 12, 1995
1.7 aaron 4: .Dt AT 1
1.3 michaels 5: .Os
1.1 deraadt 6: .Sh NAME
1.11 aaron 7: .Nm at ,
8: .Nm atq ,
9: .Nm atrm ,
10: .Nm batch
1.4 millert 11: .Nd queue, examine or delete jobs for later execution
1.1 deraadt 12: .Sh SYNOPSIS
13: .Nm at
1.22 ! millert 14: .Op Fl blmrv
! 15: .Op Fl f Ar file
! 16: .Op Fl q Ar queue
! 17: .Fl t Ar [[CC]YY]MMDDhhmm[.SS]
! 18: .Nm at
! 19: .Op Fl blmrv
1.21 millert 20: .Op Fl f Ar file
1.1 deraadt 21: .Op Fl q Ar queue
22: .Ar time
1.4 millert 23: .Nm at
24: .Fl c Ar job Op Ar job ...
1.1 deraadt 25: .Nm atq
26: .Op Fl q Ar queue
27: .Op Fl v
28: .Nm atrm
29: .Ar job
30: .Op Ar job ...
31: .Nm batch
1.21 millert 32: .Op Fl mv
33: .Op Fl f Ar file
1.4 millert 34: .Op Fl q Ar queue
35: .Op Ar time
1.1 deraadt 36: .Sh DESCRIPTION
1.13 aaron 37: .Nm at
1.1 deraadt 38: and
39: .Nm batch
1.4 millert 40: read commands from standard input or a specified file which
41: are to be executed at a later time, using
1.1 deraadt 42: .Xr sh 1 .
1.13 aaron 43: .Pp
44: The related programs are as follows:
1.16 aaron 45: .Bl -tag -width Ds
1.1 deraadt 46: .It Nm at
47: Executes commands at a specified time.
48: .It Nm atq
1.14 aaron 49: Lists the user's pending jobs, unless the user is the superuser.
1.7 aaron 50: In that case, all users' jobs are listed.
1.1 deraadt 51: .It Nm atrm
52: Deletes jobs.
53: .It Nm batch
1.14 aaron 54: Executes commands when system load levels permit.
55: In other words, when
1.4 millert 56: the load average drops below 1.5, or the value specified in the invocation of
57: .Nm atrun .
1.1 deraadt 58: .El
59: .Pp
1.13 aaron 60: The options are as follows:
61: .Bl -tag -width indent
1.21 millert 62: .It Fl b
63: An alias for
64: .Nm batch .
65: .It Fl c
66: Prints the jobs listed on the command line to standard output.
67: .It Fl f Ar file
68: Reads the job from
69: .Ar file
70: rather than standard input.
71: .It Fl l
72: An alias for
73: .Nm atq .
74: .It Fl m
75: Send mail to the user when the job has completed, even if there was no
76: output.
1.13 aaron 77: .It Fl q Ar queue
78: Uses the specified queue.
1.14 aaron 79: A queue designation consists of a single letter.
80: Valid queue designations range from
1.13 aaron 81: .Sy a
82: to
83: .Sy z
84: and
85: .Sy A
86: to
87: .Sy Z .
88: The
89: .Sy c
90: queue is the default for
91: .Nm at
92: and the
93: .Sy E
94: queue for
95: .Nm batch .
96: Queues with higher letters run with increased niceness.
97: If a job is submitted to a queue designated with an uppercase letter, it
98: is treated as if it had been submitted to batch at that time.
99: If
100: .Nm atq
101: is given a specific queue, it will only show jobs pending in that queue.
1.22 ! millert 102: .It Fl r
! 103: An alias for
! 104: .Nm atrm .
! 105: .It Fl t
! 106: Specify the job time using the \*[Px] time format.
! 107: The argument should be in the form
! 108: .Ar [[CC]YY]MMDDhhmm[.SS]
! 109: where each pair of letters represents the following:
! 110: .Pp
! 111: .Bl -tag -width indent -compact -offset indent
! 112: .It Ar CC
! 113: The first two digits of the year (the century).
! 114: .It Ar YY
! 115: The second two digits of the year.
! 116: .It Ar MM
! 117: The month of the year, from 1 to 12.
! 118: .It Ar DD
! 119: the day of the month, from 1 to 31.
! 120: .It Ar hh
! 121: The hour of the day, from 0 to 23.
! 122: .It Ar mm
! 123: The minute of the hour, from 0 to 59.
! 124: .It Ar SS
! 125: The second of the minute, from 0 to 61.
! 126: .El
! 127: .Pp
! 128: If the
! 129: .Ar CC
! 130: and
! 131: .Ar YY
! 132: letter pairs are not specified, the values default to the current
! 133: year.
! 134: If the
! 135: .Ar SS
! 136: letter pair is not specified, the value defaults to 0.
1.13 aaron 137: .It Fl v
138: For
139: .Nm atq ,
1.14 aaron 140: shows completed but not yet deleted jobs in the queue.
141: Otherwise shows the time the job will be executed.
1.13 aaron 142: .El
143: .Pp
144: .Nm at
1.4 millert 145: allows some moderately complex
146: .Ar time
1.14 aaron 147: specifications.
148: It accepts times of the form
1.1 deraadt 149: .Ar HHMM
150: or
151: .Ar HH:MM
1.4 millert 152: to run a job at a specific time of day.
153: (If that time is already past, the next day is assumed.)
1.1 deraadt 154: You may also specify
1.13 aaron 155: .Sy midnight ,
156: .Sy noon ,
1.1 deraadt 157: or
1.13 aaron 158: .Sy teatime
1.4 millert 159: (4pm)
160: and you can have a time-of-day suffixed with
1.13 aaron 161: .Dq AM
1.1 deraadt 162: or
1.13 aaron 163: .Dq PM
1.4 millert 164: for running in the morning or the evening.
165: You can also say what day the job will be run,
1.1 deraadt 166: by giving a date in the form
1.4 millert 167: .Ar \%month-name day
1.1 deraadt 168: with an optional
169: .Ar year ,
170: or giving a date of the form
1.22 ! millert 171: .Ar DD.MM.CCYY ,
! 172: .Ar DD.MM.YY ,
! 173: .Ar MM/DD/CCYY ,
! 174: .Ar MM/DD/YY ,
! 175: .Ar MMDDCCYY ,
1.1 deraadt 176: or
1.22 ! millert 177: .Ar MMDDYY .
1.13 aaron 178: .Pp
179: The year may be given as two or four digits.
1.9 alex 180: If the year is given as two digits, it is taken to occur as soon as
181: possible in the future, which may be in the next century --
182: unless it's last year, in which case it's considered to be
183: a typo.
1.13 aaron 184: .Pp
1.4 millert 185: The specification of a date must follow the specification of
186: the time of day.
1.1 deraadt 187: You can also give times like
1.13 aaron 188: .Op Sq now
189: .Sy + Ar count \%time-units ,
1.4 millert 190: where the time-units can be
1.13 aaron 191: .Sy minutes ,
192: .Sy hours ,
193: .Sy days ,
1.1 deraadt 194: or
1.13 aaron 195: .Sy weeks
1.4 millert 196: and you can tell
1.13 aaron 197: .Nm at
1.4 millert 198: to run the job today by suffixing the time with
1.13 aaron 199: .Sy today
1.4 millert 200: and to run the job tomorrow by suffixing the time with
1.13 aaron 201: .Sy tomorrow .
1.4 millert 202: .Pp
203: For example, to run a job at 4pm three days from now, you would do
1.13 aaron 204: .Ic at 4pm + 3 days .
1.7 aaron 205: To run a job at 10:00am on July 31, you would do
1.13 aaron 206: .Ic at 10am Jul 31 .
1.7 aaron 207: To run a job at 1am tomorrow, you would do
1.13 aaron 208: .Ic at 1am tomorrow .
1.4 millert 209: .Pp
1.22 ! millert 210: The
! 211: .Nm at
! 212: utility also supports the \*[Px] time format (see the
! 213: .Fl t
! 214: option).
! 215: .Pp
1.4 millert 216: For both
1.13 aaron 217: .Nm at
1.4 millert 218: and
219: .Nm batch ,
1.22 ! millert 220: commands are read from standard input (or the file specified
1.4 millert 221: with the
222: .Fl f
1.22 ! millert 223: option) and executed.
1.4 millert 224: The working directory, the environment (except for the variables
1.7 aaron 225: .Ev TERM ,
226: .Ev TERMCAP ,
227: .Ev DISPLAY ,
1.4 millert 228: and
1.13 aaron 229: .Ev _ ) ,
1.4 millert 230: and the
231: .Ar umask
232: are retained from the time of invocation.
233: An
1.13 aaron 234: .Nm at
1.4 millert 235: or
236: .Nm batch
1.10 aaron 237: command invoked from a
1.4 millert 238: .Xr su 1
1.7 aaron 239: shell will retain the current user ID.
1.4 millert 240: The user will be mailed standard error and standard output from his
1.14 aaron 241: commands, if any.
1.22 ! millert 242: Mail will be sent using
1.4 millert 243: .Xr sendmail 8 .
244: If
1.13 aaron 245: .Nm at
1.10 aaron 246: is executed from a
1.4 millert 247: .Xr su 1
248: shell, the owner of the login shell will receive the mail.
249: .Pp
1.19 millert 250: For non-root users, permission to run
251: .Nm
252: is determined by the files
1.4 millert 253: .Pa /var/at/at.allow
254: and
255: .Pa /var/at/at.deny .
1.19 millert 256: .Em Note :
257: these files must be readable by group crontab (if they exist).
1.4 millert 258: .Pp
259: If the file
260: .Pa /var/at/at.allow
261: exists, only usernames mentioned in it are allowed to use
262: .Nm at .
263: If
264: .Pa /var/at/at.allow
265: does not exist,
266: .Pa /var/at/at.deny
1.14 aaron 267: is checked.
268: Every username not mentioned in it is then allowed to use
1.4 millert 269: .Nm at .
1.19 millert 270: If neither exists, only the superuser is allowed to run
1.4 millert 271: .Nm at .
272: .Pp
1.10 aaron 273: An empty
1.4 millert 274: .Pa /var/at/at.deny
275: means that every user is allowed use these commands.
1.5 marc 276: This is the default configuration.
1.1 deraadt 277: .Sh FILES
1.19 millert 278: .Bl -tag -width /var/at/at.allow -compact
1.1 deraadt 279: .It Pa /var/at/jobs
1.7 aaron 280: directory containing job files
1.1 deraadt 281: .It Pa /var/at/spool
1.7 aaron 282: directory containing output spool files
1.4 millert 283: .It Pa /var/at/at.allow
1.7 aaron 284: allow permission control
1.4 millert 285: .It Pa /var/at/at.deny
1.7 aaron 286: deny permission control
1.19 millert 287: .It Pa /var/at/.SEQ
288: job sequence file
1.15 aaron 289: .El
1.1 deraadt 290: .Sh SEE ALSO
291: .Xr nice 1 ,
1.7 aaron 292: .Xr sh 1 ,
1.4 millert 293: .Xr umask 2 ,
1.7 aaron 294: .Xr atrun 8 ,
295: .Xr cron 8 ,
296: .Xr sendmail 8
1.17 aaron 297: .Sh AUTHORS
298: .Nm at
299: was mostly written by Thomas Koenig <ig25@rz.uni-karlsruhe.de>.
300: The time parsing routines are by David Parsons <orc@pell.chi.il.us>.
1.1 deraadt 301: .Sh BUGS
1.13 aaron 302: .Nm at
1.4 millert 303: and
304: .Nm batch
305: as presently implemented are not suitable when users are competing for
306: resources.
307: If this is the case for your site, you might want to consider another
308: batch system, such as
309: .Nm nqs .
1.12 deraadt 310: .Pp
311: .Nm atq
1.14 aaron 312: always prints the year as two digits.
313: Since
1.12 deraadt 314: .Nm at
315: only permits submission of jobs in the future, it is somewhat
316: clear which century the job will run in.