Annotation of src/usr.bin/at/at.1, Revision 1.27
1.27 ! avsm 1: .\" $OpenBSD: at.1,v 1.26 2002/07/15 19:13:29 millert Exp $
1.4 millert 2: .\" $FreeBSD: at.man,v 1.6 1997/02/22 19:54:05 peter Exp $
1.25 millert 3: .Dd May 13, 2002
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 batch
1.4 millert 9: .Nd queue, examine or delete jobs for later execution
1.1 deraadt 10: .Sh SYNOPSIS
11: .Nm at
1.25 millert 12: .Op Fl blmr
1.22 millert 13: .Op Fl f Ar file
14: .Op Fl q Ar queue
1.23 millert 15: .Fl t Ar time_arg
1.22 millert 16: .Nm at
1.25 millert 17: .Op Fl blmr
1.21 millert 18: .Op Fl f Ar file
1.1 deraadt 19: .Op Fl q Ar queue
1.23 millert 20: .Ar timespec
1.4 millert 21: .Nm at
22: .Fl c Ar job Op Ar job ...
1.1 deraadt 23: .Nm batch
1.25 millert 24: .Op Fl m
1.21 millert 25: .Op Fl f Ar file
1.4 millert 26: .Op Fl q Ar queue
1.23 millert 27: .Op Ar timespec
1.1 deraadt 28: .Sh DESCRIPTION
1.13 aaron 29: .Nm at
1.1 deraadt 30: and
31: .Nm batch
1.4 millert 32: read commands from standard input or a specified file which
1.24 millert 33: are to be executed at a later time, via the user's shell as
34: specified by the
35: .Ev SHELL
36: environment variable.
37: If
38: .Ev SHELL
39: is not set, the shell in the user's password database entry is used
40: instead.
41: If all else fails,
42: .Xr sh 1
43: will be used.
1.13 aaron 44: .Pp
45: The related programs are as follows:
1.16 aaron 46: .Bl -tag -width Ds
1.1 deraadt 47: .It Nm at
48: Executes commands at a specified time.
49: .It Nm batch
1.14 aaron 50: Executes commands when system load levels permit.
51: In other words, when
1.4 millert 52: the load average drops below 1.5, or the value specified in the invocation of
1.26 millert 53: .Xr cron 8 .
1.1 deraadt 54: .El
55: .Pp
1.13 aaron 56: The options are as follows:
57: .Bl -tag -width indent
1.21 millert 58: .It Fl b
59: An alias for
60: .Nm batch .
61: .It Fl c
62: Prints the jobs listed on the command line to standard output.
63: .It Fl f Ar file
64: Reads the job from
65: .Ar file
66: rather than standard input.
67: .It Fl l
1.25 millert 68: Lists the user's pending jobs, unless the user is the superuser.
69: In that case, all users' jobs are listed.
70: .\" XXX - should document that user names may be specified (like atq)
1.21 millert 71: .It Fl m
72: Send mail to the user when the job has completed, even if there was no
73: output.
1.13 aaron 74: .It Fl q Ar queue
75: Uses the specified queue.
1.14 aaron 76: A queue designation consists of a single letter.
77: Valid queue designations range from
1.13 aaron 78: .Sy a
79: to
80: .Sy z
81: and
82: .Sy A
83: to
84: .Sy Z .
85: The
86: .Sy c
87: queue is the default for
88: .Nm at
89: and the
90: .Sy E
91: queue for
92: .Nm batch .
93: Queues with higher letters run with increased niceness.
94: If a job is submitted to a queue designated with an uppercase letter, it
95: is treated as if it had been submitted to batch at that time.
1.25 millert 96: If the user specified the
97: .Fl l
98: option and
99: .Nm at
100: is given a specific queue, only jobs pending in that queue will be shown.
1.22 millert 101: .It Fl r
1.25 millert 102: Remove the specified job(s) from the
103: .Nm at
104: queue.
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
1.27 ! avsm 139: When used in conjunction with the
1.25 millert 140: .Fl l
141: option, shows completed but not yet deleted jobs in the queue.
1.13 aaron 142: .El
143: .Pp
144: .Nm at
1.4 millert 145: allows some moderately complex
1.23 millert 146: .Ar timespec
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
1.23 millert 212: utility also supports the time format used by
213: .Xr touch 1
214: (see the
1.22 millert 215: .Fl t
216: option).
217: .Pp
1.4 millert 218: For both
1.13 aaron 219: .Nm at
1.4 millert 220: and
221: .Nm batch ,
1.22 millert 222: commands are read from standard input (or the file specified
1.4 millert 223: with the
224: .Fl f
1.22 millert 225: option) and executed.
1.4 millert 226: The working directory, the environment (except for the variables
1.7 aaron 227: .Ev TERM ,
228: .Ev TERMCAP ,
229: .Ev DISPLAY ,
1.4 millert 230: and
1.13 aaron 231: .Ev _ ) ,
1.4 millert 232: and the
233: .Ar umask
234: are retained from the time of invocation.
235: An
1.13 aaron 236: .Nm at
1.4 millert 237: or
238: .Nm batch
1.10 aaron 239: command invoked from a
1.4 millert 240: .Xr su 1
1.7 aaron 241: shell will retain the current user ID.
1.4 millert 242: The user will be mailed standard error and standard output from his
1.14 aaron 243: commands, if any.
1.22 millert 244: Mail will be sent using
1.4 millert 245: .Xr sendmail 8 .
246: If
1.13 aaron 247: .Nm at
1.10 aaron 248: is executed from a
1.4 millert 249: .Xr su 1
250: shell, the owner of the login shell will receive the mail.
251: .Pp
1.19 millert 252: For non-root users, permission to run
253: .Nm
254: is determined by the files
1.4 millert 255: .Pa /var/at/at.allow
256: and
257: .Pa /var/at/at.deny .
1.19 millert 258: .Em Note :
259: these files must be readable by group crontab (if they exist).
1.4 millert 260: .Pp
261: If the file
262: .Pa /var/at/at.allow
263: exists, only usernames mentioned in it are allowed to use
264: .Nm at .
265: If
266: .Pa /var/at/at.allow
267: does not exist,
268: .Pa /var/at/at.deny
1.14 aaron 269: is checked.
270: Every username not mentioned in it is then allowed to use
1.4 millert 271: .Nm at .
1.19 millert 272: If neither exists, only the superuser is allowed to run
1.4 millert 273: .Nm at .
274: .Pp
1.10 aaron 275: An empty
1.4 millert 276: .Pa /var/at/at.deny
277: means that every user is allowed use these commands.
1.5 marc 278: This is the default configuration.
1.1 deraadt 279: .Sh FILES
1.19 millert 280: .Bl -tag -width /var/at/at.allow -compact
1.1 deraadt 281: .It Pa /var/at/jobs
1.7 aaron 282: directory containing job 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.23 millert 293: .Xr touch 1 ,
1.4 millert 294: .Xr umask 2 ,
1.7 aaron 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 .