Annotation of src/usr.bin/at/at.1, Revision 1.31
1.31 ! jmc 1: .\" $OpenBSD: at.1,v 1.30 2003/02/19 22:11:42 millert Exp $
1.28 millert 2: .\"
3: .\" Copyright (C) 1993, 1994 Thomas Koenig
4: .\" Copyright (C) 1993 David Parsons
5: .\" Copyright (C) 2002 Todd C. Miller
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. The name of the author(s) may not be used to endorse or promote
13: .\" products derived from this software without specific prior written
14: .\" permission.
15: .\"
16: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY EXPRESS OR
17: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
18: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
19: .\" IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY DIRECT, INDIRECT,
20: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
21: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
22: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
23: .\" THEORY OF LIABILITY, WETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
25: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26: .\"
1.25 millert 27: .Dd May 13, 2002
1.7 aaron 28: .Dt AT 1
1.3 michaels 29: .Os
1.1 deraadt 30: .Sh NAME
1.11 aaron 31: .Nm at ,
32: .Nm batch
1.4 millert 33: .Nd queue, examine or delete jobs for later execution
1.1 deraadt 34: .Sh SYNOPSIS
35: .Nm at
1.25 millert 36: .Op Fl blmr
1.22 millert 37: .Op Fl f Ar file
38: .Op Fl q Ar queue
1.23 millert 39: .Fl t Ar time_arg
1.22 millert 40: .Nm at
1.25 millert 41: .Op Fl blmr
1.21 millert 42: .Op Fl f Ar file
1.1 deraadt 43: .Op Fl q Ar queue
1.23 millert 44: .Ar timespec
1.4 millert 45: .Nm at
46: .Fl c Ar job Op Ar job ...
1.1 deraadt 47: .Nm batch
1.25 millert 48: .Op Fl m
1.21 millert 49: .Op Fl f Ar file
1.4 millert 50: .Op Fl q Ar queue
1.23 millert 51: .Op Ar timespec
1.1 deraadt 52: .Sh DESCRIPTION
1.13 aaron 53: .Nm at
1.1 deraadt 54: and
55: .Nm batch
1.4 millert 56: read commands from standard input or a specified file which
1.24 millert 57: are to be executed at a later time, via the user's shell as
58: specified by the
59: .Ev SHELL
60: environment variable.
61: If
1.31 ! jmc 62: .Ev SHELL
1.24 millert 63: is not set, the shell in the user's password database entry is used
64: instead.
65: If all else fails,
66: .Xr sh 1
67: will be used.
1.13 aaron 68: .Pp
69: The related programs are as follows:
1.16 aaron 70: .Bl -tag -width Ds
1.1 deraadt 71: .It Nm at
72: Executes commands at a specified time.
73: .It Nm batch
1.14 aaron 74: Executes commands when system load levels permit.
75: In other words, when
1.4 millert 76: the load average drops below 1.5, or the value specified in the invocation of
1.26 millert 77: .Xr cron 8 .
1.1 deraadt 78: .El
79: .Pp
1.13 aaron 80: The options are as follows:
81: .Bl -tag -width indent
1.21 millert 82: .It Fl b
83: An alias for
84: .Nm batch .
85: .It Fl c
86: Prints the jobs listed on the command line to standard output.
87: .It Fl f Ar file
88: Reads the job from
89: .Ar file
90: rather than standard input.
91: .It Fl l
1.25 millert 92: Lists the user's pending jobs, unless the user is the superuser.
93: In that case, all users' jobs are listed.
94: .\" XXX - should document that user names may be specified (like atq)
1.21 millert 95: .It Fl m
96: Send mail to the user when the job has completed, even if there was no
97: output.
1.13 aaron 98: .It Fl q Ar queue
99: Uses the specified queue.
1.14 aaron 100: A queue designation consists of a single letter.
101: Valid queue designations range from
1.13 aaron 102: .Sy a
103: to
104: .Sy z
105: and
106: .Sy A
107: to
108: .Sy Z .
109: The
110: .Sy c
111: queue is the default for
112: .Nm at
113: and the
114: .Sy E
115: queue for
116: .Nm batch .
117: Queues with higher letters run with increased niceness.
118: If a job is submitted to a queue designated with an uppercase letter, it
119: is treated as if it had been submitted to batch at that time.
1.25 millert 120: If the user specified the
121: .Fl l
122: option and
123: .Nm at
124: is given a specific queue, only jobs pending in that queue will be shown.
1.22 millert 125: .It Fl r
1.25 millert 126: Remove the specified job(s) from the
127: .Nm at
128: queue.
1.23 millert 129: .It Fl t Ar time_arg
130: Specify the job time using the format specified by
131: .Xr touch 1 .
1.22 millert 132: The argument should be in the form
133: .Ar [[CC]YY]MMDDhhmm[.SS]
134: where each pair of letters represents the following:
135: .Pp
1.23 millert 136: .Bl -tag -width Ds -compact -offset indent
1.22 millert 137: .It Ar CC
138: The first two digits of the year (the century).
139: .It Ar YY
140: The second two digits of the year.
141: .It Ar MM
142: The month of the year, from 1 to 12.
143: .It Ar DD
144: the day of the month, from 1 to 31.
145: .It Ar hh
146: The hour of the day, from 0 to 23.
147: .It Ar mm
148: The minute of the hour, from 0 to 59.
149: .It Ar SS
150: The second of the minute, from 0 to 61.
151: .El
152: .Pp
153: If the
154: .Ar CC
155: and
156: .Ar YY
157: letter pairs are not specified, the values default to the current
158: year.
159: If the
160: .Ar SS
161: letter pair is not specified, the value defaults to 0.
1.13 aaron 162: .It Fl v
1.27 avsm 163: When used in conjunction with the
1.25 millert 164: .Fl l
165: option, shows completed but not yet deleted jobs in the queue.
1.13 aaron 166: .El
167: .Pp
168: .Nm at
1.4 millert 169: allows some moderately complex
1.23 millert 170: .Ar timespec
1.14 aaron 171: specifications.
172: It accepts times of the form
1.1 deraadt 173: .Ar HHMM
174: or
175: .Ar HH:MM
1.4 millert 176: to run a job at a specific time of day.
177: (If that time is already past, the next day is assumed.)
1.1 deraadt 178: You may also specify
1.13 aaron 179: .Sy midnight ,
180: .Sy noon ,
1.1 deraadt 181: or
1.13 aaron 182: .Sy teatime
1.4 millert 183: (4pm)
184: and you can have a time-of-day suffixed with
1.13 aaron 185: .Dq AM
1.1 deraadt 186: or
1.13 aaron 187: .Dq PM
1.4 millert 188: for running in the morning or the evening.
189: You can also say what day the job will be run,
1.1 deraadt 190: by giving a date in the form
1.4 millert 191: .Ar \%month-name day
1.1 deraadt 192: with an optional
193: .Ar year ,
194: or giving a date of the form
1.22 millert 195: .Ar DD.MM.CCYY ,
196: .Ar DD.MM.YY ,
197: .Ar MM/DD/CCYY ,
198: .Ar MM/DD/YY ,
199: .Ar MMDDCCYY ,
1.1 deraadt 200: or
1.22 millert 201: .Ar MMDDYY .
1.13 aaron 202: .Pp
203: The year may be given as two or four digits.
1.9 alex 204: If the year is given as two digits, it is taken to occur as soon as
205: possible in the future, which may be in the next century --
206: unless it's last year, in which case it's considered to be
207: a typo.
1.13 aaron 208: .Pp
1.4 millert 209: The specification of a date must follow the specification of
210: the time of day.
1.1 deraadt 211: You can also give times like
1.13 aaron 212: .Op Sq now
213: .Sy + Ar count \%time-units ,
1.4 millert 214: where the time-units can be
1.13 aaron 215: .Sy minutes ,
216: .Sy hours ,
217: .Sy days ,
1.1 deraadt 218: or
1.13 aaron 219: .Sy weeks
1.4 millert 220: and you can tell
1.13 aaron 221: .Nm at
1.4 millert 222: to run the job today by suffixing the time with
1.13 aaron 223: .Sy today
1.4 millert 224: and to run the job tomorrow by suffixing the time with
1.13 aaron 225: .Sy tomorrow .
1.4 millert 226: .Pp
227: For example, to run a job at 4pm three days from now, you would do
1.13 aaron 228: .Ic at 4pm + 3 days .
1.7 aaron 229: To run a job at 10:00am on July 31, you would do
1.13 aaron 230: .Ic at 10am Jul 31 .
1.7 aaron 231: To run a job at 1am tomorrow, you would do
1.13 aaron 232: .Ic at 1am tomorrow .
1.4 millert 233: .Pp
1.22 millert 234: The
235: .Nm at
1.23 millert 236: utility also supports the time format used by
237: .Xr touch 1
238: (see the
1.22 millert 239: .Fl t
240: option).
241: .Pp
1.4 millert 242: For both
1.13 aaron 243: .Nm at
1.4 millert 244: and
245: .Nm batch ,
1.22 millert 246: commands are read from standard input (or the file specified
1.4 millert 247: with the
248: .Fl f
1.22 millert 249: option) and executed.
1.4 millert 250: The working directory, the environment (except for the variables
1.7 aaron 251: .Ev TERM ,
252: .Ev TERMCAP ,
253: .Ev DISPLAY ,
1.4 millert 254: and
1.13 aaron 255: .Ev _ ) ,
1.4 millert 256: and the
257: .Ar umask
258: are retained from the time of invocation.
259: An
1.13 aaron 260: .Nm at
1.4 millert 261: or
262: .Nm batch
1.10 aaron 263: command invoked from a
1.4 millert 264: .Xr su 1
1.7 aaron 265: shell will retain the current user ID.
1.4 millert 266: The user will be mailed standard error and standard output from his
1.14 aaron 267: commands, if any.
1.22 millert 268: Mail will be sent using
1.4 millert 269: .Xr sendmail 8 .
270: If
1.13 aaron 271: .Nm at
1.10 aaron 272: is executed from a
1.4 millert 273: .Xr su 1
274: shell, the owner of the login shell will receive the mail.
275: .Pp
1.19 millert 276: For non-root users, permission to run
277: .Nm
278: is determined by the files
1.30 millert 279: .Pa /var/cron/at.allow
1.4 millert 280: and
1.30 millert 281: .Pa /var/cron/at.deny .
1.19 millert 282: .Em Note :
283: these files must be readable by group crontab (if they exist).
1.4 millert 284: .Pp
285: If the file
1.30 millert 286: .Pa /var/cron/at.allow
1.4 millert 287: exists, only usernames mentioned in it are allowed to use
288: .Nm at .
289: If
1.30 millert 290: .Pa /var/cron/at.allow
1.4 millert 291: does not exist,
1.30 millert 292: .Pa /var/cron/at.deny
1.14 aaron 293: is checked.
294: Every username not mentioned in it is then allowed to use
1.4 millert 295: .Nm at .
1.19 millert 296: If neither exists, only the superuser is allowed to run
1.4 millert 297: .Nm at .
298: .Pp
1.10 aaron 299: An empty
1.30 millert 300: .Pa /var/cron/at.deny
1.4 millert 301: means that every user is allowed use these commands.
1.5 marc 302: This is the default configuration.
1.1 deraadt 303: .Sh FILES
1.30 millert 304: .Bl -tag -width /var/cron/at.allow -compact
305: .It Pa /var/cron/atjobs
1.7 aaron 306: directory containing job files
1.30 millert 307: .It Pa /var/cron/at.allow
1.7 aaron 308: allow permission control
1.30 millert 309: .It Pa /var/cron/at.deny
1.7 aaron 310: deny permission control
1.15 aaron 311: .El
1.1 deraadt 312: .Sh SEE ALSO
313: .Xr nice 1 ,
1.7 aaron 314: .Xr sh 1 ,
1.23 millert 315: .Xr touch 1 ,
1.4 millert 316: .Xr umask 2 ,
1.7 aaron 317: .Xr cron 8 ,
318: .Xr sendmail 8
1.17 aaron 319: .Sh AUTHORS
320: .Nm at
1.31 ! jmc 321: was mostly written by
! 322: .An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de .
! 323: The time parsing routines are by
! 324: .An David Parsons Aq orc@pell.chi.il.us .
1.1 deraadt 325: .Sh BUGS
1.13 aaron 326: .Nm at
1.4 millert 327: and
328: .Nm batch
329: as presently implemented are not suitable when users are competing for
330: resources.
331: If this is the case for your site, you might want to consider another
332: batch system, such as
333: .Nm nqs .