Annotation of src/usr.bin/at/at.1, Revision 1.51
1.51 ! jmc 1: .\" $OpenBSD: at.1,v 1.50 2014/02/15 18:29:08 schwarze 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.51 ! jmc 27: .Dd $Mdocdate: February 15 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.34 jmc 38: .Op Fl l Op Ar user ...
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.34 jmc 88: .It Fl l Op Ar user ...
89: Displays the queue of jobs which are currently awaiting execution.
90: If a
91: .Ar user
92: argument is specified, only jobs belonging to that user will
93: be displayed.
94: Unless the user is the superuser, only the user's own jobs will be
95: displayed.
1.21 millert 96: .It Fl m
97: Send mail to the user when the job has completed, even if there was no
98: output.
1.13 aaron 99: .It Fl q Ar queue
100: Uses the specified queue.
1.14 aaron 101: A queue designation consists of a single letter.
102: Valid queue designations range from
1.13 aaron 103: .Sy a
104: to
105: .Sy z
106: and
107: .Sy A
108: to
109: .Sy Z .
110: The
111: .Sy c
112: queue is the default for
113: .Nm at
114: and the
115: .Sy E
116: queue for
117: .Nm batch .
118: Queues with higher letters run with increased niceness.
119: If a job is submitted to a queue designated with an uppercase letter, it
120: is treated as if it had been submitted to batch at that time.
1.25 millert 121: If the user specified the
122: .Fl l
123: option and
124: .Nm at
125: is given a specific queue, only jobs pending in that queue will be shown.
1.34 jmc 126: .It Fl r Ar job ...
1.25 millert 127: Remove the specified job(s) from the
128: .Nm at
129: queue.
1.45 jmc 130: .It Fl t Ar time_arg
1.43 guenther 131: Specify the job time.
132: The argument should be of the form
1.50 schwarze 133: .Oo Oo Ar cc Oc Ns Ar yy Oc Ns Ar mmddHHMM Ns Op \&. Ns Ar SS ,
1.43 guenther 134: where the parts of the argument represent the following:
1.22 millert 135: .Pp
1.23 millert 136: .Bl -tag -width Ds -compact -offset indent
1.43 guenther 137: .It Ar ccyy
138: Year.
139: If yy is specified, but cc is not,
140: a value for yy between 69 and 99 results in a cc value of 19.
141: Otherwise, a cc value of 20 is used.
142: .It Ar mm
143: Month:
144: a number from 1 to 12.
145: .It Ar dd
146: Day:
147: a number from 1 to 31.
148: .It Ar HH
149: Hour:
150: a number from 0 to 23.
1.22 millert 151: .It Ar MM
1.43 guenther 152: Minute:
153: a number from 0 to 59.
1.22 millert 154: .It Ar SS
1.43 guenther 155: Second:
156: a number from 0 to 60
157: (permitting a leap second),
158: preceded by a period.
159: The default is 0.
1.22 millert 160: .El
1.13 aaron 161: .El
162: .Pp
163: .Nm at
1.4 millert 164: allows some moderately complex
1.23 millert 165: .Ar timespec
1.14 aaron 166: specifications.
167: It accepts times of the form
1.1 deraadt 168: .Ar HHMM
169: or
170: .Ar HH:MM
1.4 millert 171: to run a job at a specific time of day.
172: (If that time is already past, the next day is assumed.)
1.1 deraadt 173: You may also specify
1.50 schwarze 174: .Cm midnight ,
175: .Cm noon ,
1.1 deraadt 176: or
1.50 schwarze 177: .Cm teatime
1.4 millert 178: (4pm)
179: and you can have a time-of-day suffixed with
1.50 schwarze 180: .Cm AM
1.1 deraadt 181: or
1.50 schwarze 182: .Cm PM
1.4 millert 183: for running in the morning or the evening.
184: You can also say what day the job will be run,
1.1 deraadt 185: by giving a date in the form
1.4 millert 186: .Ar \%month-name day
1.1 deraadt 187: with an optional
188: .Ar year ,
189: or giving a date of the form
1.44 jmc 190: .Ar dd.mm.ccyy ,
191: .Ar dd.mm.yy ,
192: .Ar mm/dd/ccyy ,
193: .Ar mm/dd/yy ,
194: .Ar mmddccyy ,
1.1 deraadt 195: or
1.44 jmc 196: .Ar mmddyy .
1.13 aaron 197: .Pp
198: The year may be given as two or four digits.
1.9 alex 199: If the year is given as two digits, it is taken to occur as soon as
200: possible in the future, which may be in the next century --
201: unless it's last year, in which case it's considered to be
202: a typo.
1.13 aaron 203: .Pp
1.4 millert 204: The specification of a date must follow the specification of
205: the time of day.
1.1 deraadt 206: You can also give times like
1.50 schwarze 207: .Oo Cm now Oc Cm + Ar count time-units ,
1.4 millert 208: where the time-units can be
1.50 schwarze 209: .Cm minutes ,
210: .Cm hours ,
211: .Cm days ,
212: .Cm weeks ,
213: .Cm months ,
1.1 deraadt 214: or
1.50 schwarze 215: .Cm years
1.48 millert 216: (the singular forms are also accepted).
217: You can tell
1.13 aaron 218: .Nm at
1.4 millert 219: to run the job today by suffixing the time with
1.50 schwarze 220: .Cm today
1.4 millert 221: and to run the job tomorrow by suffixing the time with
1.50 schwarze 222: .Cm tomorrow .
1.48 millert 223: The
1.50 schwarze 224: .Cm next
1.48 millert 225: keyword may be used as an alias for
1.50 schwarze 226: .Cm + 1 .
1.4 millert 227: .Pp
228: For example, to run a job at 4pm three days from now, you would do
1.13 aaron 229: .Ic at 4pm + 3 days .
1.7 aaron 230: To run a job at 10:00am on July 31, you would do
1.13 aaron 231: .Ic at 10am Jul 31 .
1.7 aaron 232: To run a job at 1am tomorrow, you would do
1.13 aaron 233: .Ic at 1am tomorrow .
1.48 millert 234: To run a job at midnight in one week's time, you would do
235: .Ic at midnight next week .
1.4 millert 236: .Pp
1.22 millert 237: The
238: .Nm at
1.23 millert 239: utility also supports the time format used by
240: .Xr touch 1
241: (see the
1.22 millert 242: .Fl t
243: option).
244: .Pp
1.4 millert 245: For both
1.13 aaron 246: .Nm at
1.4 millert 247: and
248: .Nm batch ,
1.22 millert 249: commands are read from standard input (or the file specified
1.4 millert 250: with the
251: .Fl f
1.22 millert 252: option) and executed.
1.4 millert 253: The working directory, the environment (except for the variables
1.7 aaron 254: .Ev TERM ,
255: .Ev TERMCAP ,
256: .Ev DISPLAY ,
1.4 millert 257: and
1.13 aaron 258: .Ev _ ) ,
1.4 millert 259: and the
260: .Ar umask
261: are retained from the time of invocation.
262: An
1.13 aaron 263: .Nm at
1.4 millert 264: or
265: .Nm batch
1.10 aaron 266: command invoked from a
1.4 millert 267: .Xr su 1
1.7 aaron 268: shell will retain the current user ID.
1.4 millert 269: The user will be mailed standard error and standard output from his
1.14 aaron 270: commands, if any.
1.22 millert 271: Mail will be sent using
1.4 millert 272: .Xr sendmail 8 .
273: If
1.13 aaron 274: .Nm at
1.10 aaron 275: is executed from a
1.4 millert 276: .Xr su 1
277: shell, the owner of the login shell will receive the mail.
278: .Pp
1.19 millert 279: For non-root users, permission to run
280: .Nm
281: is determined by the files
1.30 millert 282: .Pa /var/cron/at.allow
1.4 millert 283: and
1.30 millert 284: .Pa /var/cron/at.deny .
1.19 millert 285: .Em Note :
286: these files must be readable by group crontab (if they exist).
1.4 millert 287: .Pp
288: If the file
1.30 millert 289: .Pa /var/cron/at.allow
1.4 millert 290: exists, only usernames mentioned in it are allowed to use
291: .Nm at .
292: If
1.30 millert 293: .Pa /var/cron/at.allow
1.4 millert 294: does not exist,
1.30 millert 295: .Pa /var/cron/at.deny
1.14 aaron 296: is checked.
297: Every username not mentioned in it is then allowed to use
1.4 millert 298: .Nm at .
1.19 millert 299: If neither exists, only the superuser is allowed to run
1.4 millert 300: .Nm at .
301: .Pp
1.10 aaron 302: An empty
1.30 millert 303: .Pa /var/cron/at.deny
1.37 jmc 304: means that every user is allowed to use these commands.
1.5 marc 305: This is the default configuration.
1.42 jmc 306: .Sh FILES
307: .Bl -tag -width /var/cron/at.allow -compact
308: .It Pa /var/cron/atjobs
309: directory containing job files
310: .It Pa /var/cron/at.allow
311: allow permission control
312: .It Pa /var/cron/at.deny
313: deny permission control
314: .El
315: .Sh EXIT STATUS
1.41 jmc 316: The
317: .Nm
318: utility exits with one of the following values:
319: .Pp
1.42 jmc 320: .Bl -tag -width Ds -offset indent -compact
1.41 jmc 321: .It 0
322: Jobs were successfully submitted, removed, or listed.
323: .It \*(Gt0
324: An error occurred.
1.15 aaron 325: .El
1.1 deraadt 326: .Sh SEE ALSO
1.34 jmc 327: .Xr atq 1 ,
328: .Xr atrm 1 ,
1.1 deraadt 329: .Xr nice 1 ,
1.7 aaron 330: .Xr sh 1 ,
1.23 millert 331: .Xr touch 1 ,
1.4 millert 332: .Xr umask 2 ,
1.7 aaron 333: .Xr cron 8 ,
334: .Xr sendmail 8
1.35 jmc 335: .Sh STANDARDS
336: The
337: .Nm
338: and
339: .Nm batch
340: utilities are compliant with the
1.38 jmc 341: .St -p1003.1-2008
1.51 ! jmc 342: specification,
! 343: except behaviour for the
! 344: .Fl l
! 345: flag differs.
1.35 jmc 346: .Pp
347: The
348: .Nm
349: flags
350: .Op Fl bc
351: and the
352: .Nm batch
353: flags
1.51 ! jmc 354: .Op Fl fmq ,
! 355: as well as
! 356: the
! 357: .Cm teatime
! 358: keyword,
1.35 jmc 359: are extensions to that specification.
1.39 jmc 360: .Pp
1.47 jmc 361: .St -p1003.1-2008
362: states that
363: .Nm batch
364: jobs are submitted to the queue
365: .Qq with no time constraints ;
366: this implementation permits a
367: .Ar timespec
368: argument.
1.49 jmc 369: .Pp
370: The at.allow/deny mechanism is marked by
371: .St -p1003.1-2008
372: as being an
373: X/Open System Interfaces
374: option.
1.17 aaron 375: .Sh AUTHORS
1.33 jaredy 376: .An -nosplit
1.17 aaron 377: .Nm at
1.31 jmc 378: was mostly written by
1.46 schwarze 379: .An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de .
1.31 jmc 380: The time parsing routines are by
1.46 schwarze 381: .An David Parsons Aq Mt orc@pell.chi.il.us .
1.1 deraadt 382: .Sh BUGS
1.13 aaron 383: .Nm at
1.4 millert 384: and
385: .Nm batch
386: as presently implemented are not suitable when users are competing for
387: resources.
388: If this is the case for your site, you might want to consider another
389: batch system, such as
390: .Nm nqs .
![[BACK]](/icons/back.gif){kind=icon}
Return to at.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / at