Annotation of src/usr.bin/at/at.1, Revision 1.55
1.55 ! schwarze 1: .\" $OpenBSD: at.1,v 1.54 2018/01/31 16:46:13 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
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.55 ! schwarze 27: .Dd $Mdocdate: January 31 2018 $
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
1.55 ! schwarze 199: possible in the future, which may be in the next century \(em
1.9 alex 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.54 millert 253: .Ev BASH_VERSINFO ,
254: .Ev DISPLAY ,
255: .Ev EUID ,
256: .Ev GROUPS ,
257: .Ev PPID ,
258: .Ev SHELLOPTS ,
259: .Ev SSH_AGENT_PID ,
260: .Ev SSH_AUTH_SOCK ,
1.7 aaron 261: .Ev TERM ,
262: .Ev TERMCAP ,
1.54 millert 263: .Ev UID ,
1.4 millert 264: and
1.13 aaron 265: .Ev _ ) ,
1.4 millert 266: and the
267: .Ar umask
268: are retained from the time of invocation.
269: An
1.13 aaron 270: .Nm at
1.4 millert 271: or
272: .Nm batch
1.10 aaron 273: command invoked from a
1.4 millert 274: .Xr su 1
1.7 aaron 275: shell will retain the current user ID.
1.4 millert 276: The user will be mailed standard error and standard output from his
1.14 aaron 277: commands, if any.
1.4 millert 278: If
1.13 aaron 279: .Nm at
1.10 aaron 280: is executed from a
1.4 millert 281: .Xr su 1
282: shell, the owner of the login shell will receive the mail.
283: .Pp
1.19 millert 284: For non-root users, permission to run
285: .Nm
286: is determined by the files
1.30 millert 287: .Pa /var/cron/at.allow
1.4 millert 288: and
1.30 millert 289: .Pa /var/cron/at.deny .
1.19 millert 290: .Em Note :
291: these files must be readable by group crontab (if they exist).
1.4 millert 292: .Pp
293: If the file
1.30 millert 294: .Pa /var/cron/at.allow
1.4 millert 295: exists, only usernames mentioned in it are allowed to use
296: .Nm at .
297: If
1.30 millert 298: .Pa /var/cron/at.allow
1.4 millert 299: does not exist,
1.30 millert 300: .Pa /var/cron/at.deny
1.14 aaron 301: is checked.
302: Every username not mentioned in it is then allowed to use
1.4 millert 303: .Nm at .
1.19 millert 304: If neither exists, only the superuser is allowed to run
1.4 millert 305: .Nm at .
306: .Pp
1.10 aaron 307: An empty
1.30 millert 308: .Pa /var/cron/at.deny
1.37 jmc 309: means that every user is allowed to use these commands.
1.5 marc 310: This is the default configuration.
1.42 jmc 311: .Sh FILES
312: .Bl -tag -width /var/cron/at.allow -compact
313: .It Pa /var/cron/atjobs
314: directory containing job files
315: .It Pa /var/cron/at.allow
316: allow permission control
317: .It Pa /var/cron/at.deny
318: deny permission control
319: .El
320: .Sh EXIT STATUS
1.41 jmc 321: The
322: .Nm
323: utility exits with one of the following values:
324: .Pp
1.42 jmc 325: .Bl -tag -width Ds -offset indent -compact
1.41 jmc 326: .It 0
327: Jobs were successfully submitted, removed, or listed.
1.52 jmc 328: .It >0
1.41 jmc 329: An error occurred.
1.15 aaron 330: .El
1.1 deraadt 331: .Sh SEE ALSO
1.34 jmc 332: .Xr atq 1 ,
333: .Xr atrm 1 ,
1.1 deraadt 334: .Xr nice 1 ,
1.7 aaron 335: .Xr sh 1 ,
1.23 millert 336: .Xr touch 1 ,
1.4 millert 337: .Xr umask 2 ,
1.52 jmc 338: .Xr cron 8
1.35 jmc 339: .Sh STANDARDS
340: The
341: .Nm
342: and
343: .Nm batch
344: utilities are compliant with the
1.38 jmc 345: .St -p1003.1-2008
1.53 millert 346: specification.
1.35 jmc 347: .Pp
348: The
349: .Nm
350: flags
351: .Op Fl bc
352: and the
353: .Nm batch
354: flags
1.51 jmc 355: .Op Fl fmq ,
356: as well as
357: the
358: .Cm teatime
359: keyword,
1.35 jmc 360: are extensions to that specification.
1.39 jmc 361: .Pp
1.47 jmc 362: .St -p1003.1-2008
363: states that
364: .Nm batch
365: jobs are submitted to the queue
366: .Qq with no time constraints ;
367: this implementation permits a
368: .Ar timespec
369: argument.
1.49 jmc 370: .Pp
371: The at.allow/deny mechanism is marked by
372: .St -p1003.1-2008
373: as being an
374: X/Open System Interfaces
375: option.
1.17 aaron 376: .Sh AUTHORS
1.33 jaredy 377: .An -nosplit
1.17 aaron 378: .Nm at
1.31 jmc 379: was mostly written by
1.46 schwarze 380: .An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de .
1.31 jmc 381: The time parsing routines are by
1.46 schwarze 382: .An David Parsons Aq Mt orc@pell.chi.il.us .
1.1 deraadt 383: .Sh BUGS
1.13 aaron 384: .Nm at
1.4 millert 385: and
386: .Nm batch
387: as presently implemented are not suitable when users are competing for
388: resources.
389: If this is the case for your site, you might want to consider another
390: batch system, such as
391: .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