Annotation of src/usr.bin/at/at.1, Revision 1.53
1.53 ! millert 1: .\" $OpenBSD: at.1,v 1.52 2014/09/16 15:56:36 jmc 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
1.40 krw 23: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
1.28 millert 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.53 ! millert 27: .Dd $Mdocdate: September 16 2014 $
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.34 jmc 36: .Op Fl bm
1.22 millert 37: .Op Fl f Ar file
1.53 ! millert 38: .Op Fl l Op Ar job ...
1.22 millert 39: .Op Fl q Ar queue
1.34 jmc 40: .Fl t Ar time_arg | timespec
1.4 millert 41: .Nm at
1.32 jmc 42: .Fl c | r
1.34 jmc 43: .Ar job ...
1.1 deraadt 44: .Nm batch
1.25 millert 45: .Op Fl m
1.21 millert 46: .Op Fl f Ar file
1.4 millert 47: .Op Fl q Ar queue
1.23 millert 48: .Op Ar timespec
1.1 deraadt 49: .Sh DESCRIPTION
1.13 aaron 50: .Nm at
1.1 deraadt 51: and
52: .Nm batch
1.4 millert 53: read commands from standard input or a specified file which
1.24 millert 54: are to be executed at a later time, via the user's shell as
55: specified by the
56: .Ev SHELL
57: environment variable.
58: If
1.31 jmc 59: .Ev SHELL
1.24 millert 60: is not set, the shell in the user's password database entry is used
61: instead.
62: If all else fails,
63: .Xr sh 1
64: will be used.
1.13 aaron 65: .Pp
66: The related programs are as follows:
1.16 aaron 67: .Bl -tag -width Ds
1.1 deraadt 68: .It Nm at
69: Executes commands at a specified time.
70: .It Nm batch
1.14 aaron 71: Executes commands when system load levels permit.
72: In other words, when
1.4 millert 73: the load average drops below 1.5, or the value specified in the invocation of
1.26 millert 74: .Xr cron 8 .
1.1 deraadt 75: .El
76: .Pp
1.13 aaron 77: The options are as follows:
78: .Bl -tag -width indent
1.21 millert 79: .It Fl b
80: An alias for
81: .Nm batch .
1.34 jmc 82: .It Fl c Ar job ...
1.21 millert 83: Prints the jobs listed on the command line to standard output.
84: .It Fl f Ar file
85: Reads the job from
86: .Ar file
87: rather than standard input.
1.53 ! millert 88: .It Fl l Op Ar job ...
1.34 jmc 89: Displays the queue of jobs which are currently awaiting execution.
90: If a
1.53 ! millert 91: .Ar job
! 92: argument is specified, only the specified jobs will be displayed.
1.34 jmc 93: Unless the user is the superuser, only the user's own jobs will be
94: displayed.
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.34 jmc 125: .It Fl r Ar job ...
1.25 millert 126: Remove the specified job(s) from the
127: .Nm at
128: queue.
1.45 jmc 129: .It Fl t Ar time_arg
1.43 guenther 130: Specify the job time.
131: The argument should be of the form
1.50 schwarze 132: .Oo Oo Ar cc Oc Ns Ar yy Oc Ns Ar mmddHHMM Ns Op \&. Ns Ar SS ,
1.43 guenther 133: where the parts of the argument represent the following:
1.22 millert 134: .Pp
1.23 millert 135: .Bl -tag -width Ds -compact -offset indent
1.43 guenther 136: .It Ar ccyy
137: Year.
138: If yy is specified, but cc is not,
139: a value for yy between 69 and 99 results in a cc value of 19.
140: Otherwise, a cc value of 20 is used.
141: .It Ar mm
142: Month:
143: a number from 1 to 12.
144: .It Ar dd
145: Day:
146: a number from 1 to 31.
147: .It Ar HH
148: Hour:
149: a number from 0 to 23.
1.22 millert 150: .It Ar MM
1.43 guenther 151: Minute:
152: a number from 0 to 59.
1.22 millert 153: .It Ar SS
1.43 guenther 154: Second:
155: a number from 0 to 60
156: (permitting a leap second),
157: preceded by a period.
158: The default is 0.
1.22 millert 159: .El
1.13 aaron 160: .El
161: .Pp
162: .Nm at
1.4 millert 163: allows some moderately complex
1.23 millert 164: .Ar timespec
1.14 aaron 165: specifications.
166: It accepts times of the form
1.1 deraadt 167: .Ar HHMM
168: or
169: .Ar HH:MM
1.4 millert 170: to run a job at a specific time of day.
171: (If that time is already past, the next day is assumed.)
1.1 deraadt 172: You may also specify
1.50 schwarze 173: .Cm midnight ,
174: .Cm noon ,
1.1 deraadt 175: or
1.50 schwarze 176: .Cm teatime
1.4 millert 177: (4pm)
178: and you can have a time-of-day suffixed with
1.50 schwarze 179: .Cm AM
1.1 deraadt 180: or
1.50 schwarze 181: .Cm PM
1.4 millert 182: for running in the morning or the evening.
183: You can also say what day the job will be run,
1.1 deraadt 184: by giving a date in the form
1.4 millert 185: .Ar \%month-name day
1.1 deraadt 186: with an optional
187: .Ar year ,
188: or giving a date of the form
1.44 jmc 189: .Ar dd.mm.ccyy ,
190: .Ar dd.mm.yy ,
191: .Ar mm/dd/ccyy ,
192: .Ar mm/dd/yy ,
193: .Ar mmddccyy ,
1.1 deraadt 194: or
1.44 jmc 195: .Ar mmddyy .
1.13 aaron 196: .Pp
197: The year may be given as two or four digits.
1.9 alex 198: If the year is given as two digits, it is taken to occur as soon as
199: possible in the future, which may be in the next century --
200: unless it's last year, in which case it's considered to be
201: a typo.
1.13 aaron 202: .Pp
1.4 millert 203: The specification of a date must follow the specification of
204: the time of day.
1.1 deraadt 205: You can also give times like
1.50 schwarze 206: .Oo Cm now Oc Cm + Ar count time-units ,
1.4 millert 207: where the time-units can be
1.50 schwarze 208: .Cm minutes ,
209: .Cm hours ,
210: .Cm days ,
211: .Cm weeks ,
212: .Cm months ,
1.1 deraadt 213: or
1.50 schwarze 214: .Cm years
1.48 millert 215: (the singular forms are also accepted).
216: You can tell
1.13 aaron 217: .Nm at
1.4 millert 218: to run the job today by suffixing the time with
1.50 schwarze 219: .Cm today
1.4 millert 220: and to run the job tomorrow by suffixing the time with
1.50 schwarze 221: .Cm tomorrow .
1.48 millert 222: The
1.50 schwarze 223: .Cm next
1.48 millert 224: keyword may be used as an alias for
1.50 schwarze 225: .Cm + 1 .
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.48 millert 233: To run a job at midnight in one week's time, you would do
234: .Ic at midnight next week .
1.4 millert 235: .Pp
1.22 millert 236: The
237: .Nm at
1.23 millert 238: utility also supports the time format used by
239: .Xr touch 1
240: (see the
1.22 millert 241: .Fl t
242: option).
243: .Pp
1.4 millert 244: For both
1.13 aaron 245: .Nm at
1.4 millert 246: and
247: .Nm batch ,
1.22 millert 248: commands are read from standard input (or the file specified
1.4 millert 249: with the
250: .Fl f
1.22 millert 251: option) and executed.
1.4 millert 252: The working directory, the environment (except for the variables
1.7 aaron 253: .Ev TERM ,
254: .Ev TERMCAP ,
255: .Ev DISPLAY ,
1.4 millert 256: and
1.13 aaron 257: .Ev _ ) ,
1.4 millert 258: and the
259: .Ar umask
260: are retained from the time of invocation.
261: An
1.13 aaron 262: .Nm at
1.4 millert 263: or
264: .Nm batch
1.10 aaron 265: command invoked from a
1.4 millert 266: .Xr su 1
1.7 aaron 267: shell will retain the current user ID.
1.4 millert 268: The user will be mailed standard error and standard output from his
1.14 aaron 269: commands, if any.
1.4 millert 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.37 jmc 301: means that every user is allowed to use these commands.
1.5 marc 302: This is the default configuration.
1.42 jmc 303: .Sh FILES
304: .Bl -tag -width /var/cron/at.allow -compact
305: .It Pa /var/cron/atjobs
306: directory containing job files
307: .It Pa /var/cron/at.allow
308: allow permission control
309: .It Pa /var/cron/at.deny
310: deny permission control
311: .El
312: .Sh EXIT STATUS
1.41 jmc 313: The
314: .Nm
315: utility exits with one of the following values:
316: .Pp
1.42 jmc 317: .Bl -tag -width Ds -offset indent -compact
1.41 jmc 318: .It 0
319: Jobs were successfully submitted, removed, or listed.
1.52 jmc 320: .It >0
1.41 jmc 321: An error occurred.
1.15 aaron 322: .El
1.1 deraadt 323: .Sh SEE ALSO
1.34 jmc 324: .Xr atq 1 ,
325: .Xr atrm 1 ,
1.1 deraadt 326: .Xr nice 1 ,
1.7 aaron 327: .Xr sh 1 ,
1.23 millert 328: .Xr touch 1 ,
1.4 millert 329: .Xr umask 2 ,
1.52 jmc 330: .Xr cron 8
1.35 jmc 331: .Sh STANDARDS
332: The
333: .Nm
334: and
335: .Nm batch
336: utilities are compliant with the
1.38 jmc 337: .St -p1003.1-2008
1.53 ! millert 338: specification.
1.35 jmc 339: .Pp
340: The
341: .Nm
342: flags
343: .Op Fl bc
344: and the
345: .Nm batch
346: flags
1.51 jmc 347: .Op Fl fmq ,
348: as well as
349: the
350: .Cm teatime
351: keyword,
1.35 jmc 352: are extensions to that specification.
1.39 jmc 353: .Pp
1.47 jmc 354: .St -p1003.1-2008
355: states that
356: .Nm batch
357: jobs are submitted to the queue
358: .Qq with no time constraints ;
359: this implementation permits a
360: .Ar timespec
361: argument.
1.49 jmc 362: .Pp
363: The at.allow/deny mechanism is marked by
364: .St -p1003.1-2008
365: as being an
366: X/Open System Interfaces
367: option.
1.17 aaron 368: .Sh AUTHORS
1.33 jaredy 369: .An -nosplit
1.17 aaron 370: .Nm at
1.31 jmc 371: was mostly written by
1.46 schwarze 372: .An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de .
1.31 jmc 373: The time parsing routines are by
1.46 schwarze 374: .An David Parsons Aq Mt orc@pell.chi.il.us .
1.1 deraadt 375: .Sh BUGS
1.13 aaron 376: .Nm at
1.4 millert 377: and
378: .Nm batch
379: as presently implemented are not suitable when users are competing for
380: resources.
381: If this is the case for your site, you might want to consider another
382: batch system, such as
383: .Nm nqs .