Annotation of src/usr.bin/at/at.1, Revision 1.23
1.23 ! millert 1: .\" $OpenBSD: at.1,v 1.22 2002/05/11 23:02:33 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
1.23 ! millert 17: .Fl t Ar time_arg
1.22 millert 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
1.23 ! millert 22: .Ar timespec
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
1.23 ! millert 35: .Op Ar timespec
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 .
1.23 ! millert 105: .It Fl t Ar time_arg
! 106: Specify the job time using the format specified by
! 107: .Xr touch 1 .
1.22 millert 108: The argument should be in the form
109: .Ar [[CC]YY]MMDDhhmm[.SS]
110: where each pair of letters represents the following:
111: .Pp
1.23 ! millert 112: .Bl -tag -width Ds -compact -offset indent
1.22 millert 113: .It Ar CC
114: The first two digits of the year (the century).
115: .It Ar YY
116: The second two digits of the year.
117: .It Ar MM
118: The month of the year, from 1 to 12.
119: .It Ar DD
120: the day of the month, from 1 to 31.
121: .It Ar hh
122: The hour of the day, from 0 to 23.
123: .It Ar mm
124: The minute of the hour, from 0 to 59.
125: .It Ar SS
126: The second of the minute, from 0 to 61.
127: .El
128: .Pp
129: If the
130: .Ar CC
131: and
132: .Ar YY
133: letter pairs are not specified, the values default to the current
134: year.
135: If the
136: .Ar SS
137: letter pair is not specified, the value defaults to 0.
1.13 aaron 138: .It Fl v
139: For
140: .Nm atq ,
1.14 aaron 141: shows completed but not yet deleted jobs in the queue.
142: Otherwise shows the time the job will be executed.
1.13 aaron 143: .El
144: .Pp
145: .Nm at
1.4 millert 146: allows some moderately complex
1.23 ! millert 147: .Ar timespec
1.14 aaron 148: specifications.
149: It accepts times of the form
1.1 deraadt 150: .Ar HHMM
151: or
152: .Ar HH:MM
1.4 millert 153: to run a job at a specific time of day.
154: (If that time is already past, the next day is assumed.)
1.1 deraadt 155: You may also specify
1.13 aaron 156: .Sy midnight ,
157: .Sy noon ,
1.1 deraadt 158: or
1.13 aaron 159: .Sy teatime
1.4 millert 160: (4pm)
161: and you can have a time-of-day suffixed with
1.13 aaron 162: .Dq AM
1.1 deraadt 163: or
1.13 aaron 164: .Dq PM
1.4 millert 165: for running in the morning or the evening.
166: You can also say what day the job will be run,
1.1 deraadt 167: by giving a date in the form
1.4 millert 168: .Ar \%month-name day
1.1 deraadt 169: with an optional
170: .Ar year ,
171: or giving a date of the form
1.22 millert 172: .Ar DD.MM.CCYY ,
173: .Ar DD.MM.YY ,
174: .Ar MM/DD/CCYY ,
175: .Ar MM/DD/YY ,
176: .Ar MMDDCCYY ,
1.1 deraadt 177: or
1.22 millert 178: .Ar MMDDYY .
1.13 aaron 179: .Pp
180: The year may be given as two or four digits.
1.9 alex 181: If the year is given as two digits, it is taken to occur as soon as
182: possible in the future, which may be in the next century --
183: unless it's last year, in which case it's considered to be
184: a typo.
1.13 aaron 185: .Pp
1.4 millert 186: The specification of a date must follow the specification of
187: the time of day.
1.1 deraadt 188: You can also give times like
1.13 aaron 189: .Op Sq now
190: .Sy + Ar count \%time-units ,
1.4 millert 191: where the time-units can be
1.13 aaron 192: .Sy minutes ,
193: .Sy hours ,
194: .Sy days ,
1.1 deraadt 195: or
1.13 aaron 196: .Sy weeks
1.4 millert 197: and you can tell
1.13 aaron 198: .Nm at
1.4 millert 199: to run the job today by suffixing the time with
1.13 aaron 200: .Sy today
1.4 millert 201: and to run the job tomorrow by suffixing the time with
1.13 aaron 202: .Sy tomorrow .
1.4 millert 203: .Pp
204: For example, to run a job at 4pm three days from now, you would do
1.13 aaron 205: .Ic at 4pm + 3 days .
1.7 aaron 206: To run a job at 10:00am on July 31, you would do
1.13 aaron 207: .Ic at 10am Jul 31 .
1.7 aaron 208: To run a job at 1am tomorrow, you would do
1.13 aaron 209: .Ic at 1am tomorrow .
1.4 millert 210: .Pp
1.22 millert 211: The
212: .Nm at
1.23 ! millert 213: utility also supports the time format used by
! 214: .Xr touch 1
! 215: (see the
1.22 millert 216: .Fl t
217: option).
218: .Pp
1.4 millert 219: For both
1.13 aaron 220: .Nm at
1.4 millert 221: and
222: .Nm batch ,
1.22 millert 223: commands are read from standard input (or the file specified
1.4 millert 224: with the
225: .Fl f
1.22 millert 226: option) and executed.
1.4 millert 227: The working directory, the environment (except for the variables
1.7 aaron 228: .Ev TERM ,
229: .Ev TERMCAP ,
230: .Ev DISPLAY ,
1.4 millert 231: and
1.13 aaron 232: .Ev _ ) ,
1.4 millert 233: and the
234: .Ar umask
235: are retained from the time of invocation.
236: An
1.13 aaron 237: .Nm at
1.4 millert 238: or
239: .Nm batch
1.10 aaron 240: command invoked from a
1.4 millert 241: .Xr su 1
1.7 aaron 242: shell will retain the current user ID.
1.4 millert 243: The user will be mailed standard error and standard output from his
1.14 aaron 244: commands, if any.
1.22 millert 245: Mail will be sent using
1.4 millert 246: .Xr sendmail 8 .
247: If
1.13 aaron 248: .Nm at
1.10 aaron 249: is executed from a
1.4 millert 250: .Xr su 1
251: shell, the owner of the login shell will receive the mail.
252: .Pp
1.19 millert 253: For non-root users, permission to run
254: .Nm
255: is determined by the files
1.4 millert 256: .Pa /var/at/at.allow
257: and
258: .Pa /var/at/at.deny .
1.19 millert 259: .Em Note :
260: these files must be readable by group crontab (if they exist).
1.4 millert 261: .Pp
262: If the file
263: .Pa /var/at/at.allow
264: exists, only usernames mentioned in it are allowed to use
265: .Nm at .
266: If
267: .Pa /var/at/at.allow
268: does not exist,
269: .Pa /var/at/at.deny
1.14 aaron 270: is checked.
271: Every username not mentioned in it is then allowed to use
1.4 millert 272: .Nm at .
1.19 millert 273: If neither exists, only the superuser is allowed to run
1.4 millert 274: .Nm at .
275: .Pp
1.10 aaron 276: An empty
1.4 millert 277: .Pa /var/at/at.deny
278: means that every user is allowed use these commands.
1.5 marc 279: This is the default configuration.
1.1 deraadt 280: .Sh FILES
1.19 millert 281: .Bl -tag -width /var/at/at.allow -compact
1.1 deraadt 282: .It Pa /var/at/jobs
1.7 aaron 283: directory containing job files
1.1 deraadt 284: .It Pa /var/at/spool
1.7 aaron 285: directory containing output spool files
1.4 millert 286: .It Pa /var/at/at.allow
1.7 aaron 287: allow permission control
1.4 millert 288: .It Pa /var/at/at.deny
1.7 aaron 289: deny permission control
1.19 millert 290: .It Pa /var/at/.SEQ
291: job sequence file
1.15 aaron 292: .El
1.1 deraadt 293: .Sh SEE ALSO
294: .Xr nice 1 ,
1.7 aaron 295: .Xr sh 1 ,
1.23 ! millert 296: .Xr touch 1 ,
1.4 millert 297: .Xr umask 2 ,
1.7 aaron 298: .Xr atrun 8 ,
299: .Xr cron 8 ,
300: .Xr sendmail 8
1.17 aaron 301: .Sh AUTHORS
302: .Nm at
303: was mostly written by Thomas Koenig <ig25@rz.uni-karlsruhe.de>.
304: The time parsing routines are by David Parsons <orc@pell.chi.il.us>.
1.1 deraadt 305: .Sh BUGS
1.13 aaron 306: .Nm at
1.4 millert 307: and
308: .Nm batch
309: as presently implemented are not suitable when users are competing for
310: resources.
311: If this is the case for your site, you might want to consider another
312: batch system, such as
313: .Nm nqs .
1.12 deraadt 314: .Pp
315: .Nm atq
1.14 aaron 316: always prints the year as two digits.
317: Since
1.12 deraadt 318: .Nm at
319: only permits submission of jobs in the future, it is somewhat
320: clear which century the job will run in.