Annotation of src/usr.bin/at/at.1, Revision 1.47
1.47 ! jmc 1: .\" $OpenBSD: at.1,v 1.46 2013/07/16 00:07:51 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.47 ! jmc 27: .Dd $Mdocdate: July 16 2013 $
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
133: [[cc]yy]mmddHHMM[.SS],
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.13 aaron 174: .Sy midnight ,
175: .Sy noon ,
1.1 deraadt 176: or
1.13 aaron 177: .Sy teatime
1.4 millert 178: (4pm)
179: and you can have a time-of-day suffixed with
1.13 aaron 180: .Dq AM
1.1 deraadt 181: or
1.13 aaron 182: .Dq 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.13 aaron 207: .Op Sq now
208: .Sy + Ar count \%time-units ,
1.4 millert 209: where the time-units can be
1.13 aaron 210: .Sy minutes ,
211: .Sy hours ,
212: .Sy days ,
1.1 deraadt 213: or
1.13 aaron 214: .Sy weeks
1.4 millert 215: and you can tell
1.13 aaron 216: .Nm at
1.4 millert 217: to run the job today by suffixing the time with
1.13 aaron 218: .Sy today
1.4 millert 219: and to run the job tomorrow by suffixing the time with
1.13 aaron 220: .Sy tomorrow .
1.4 millert 221: .Pp
222: For example, to run a job at 4pm three days from now, you would do
1.13 aaron 223: .Ic at 4pm + 3 days .
1.7 aaron 224: To run a job at 10:00am on July 31, you would do
1.13 aaron 225: .Ic at 10am Jul 31 .
1.7 aaron 226: To run a job at 1am tomorrow, you would do
1.13 aaron 227: .Ic at 1am tomorrow .
1.4 millert 228: .Pp
1.22 millert 229: The
230: .Nm at
1.23 millert 231: utility also supports the time format used by
232: .Xr touch 1
233: (see the
1.22 millert 234: .Fl t
235: option).
236: .Pp
1.4 millert 237: For both
1.13 aaron 238: .Nm at
1.4 millert 239: and
240: .Nm batch ,
1.22 millert 241: commands are read from standard input (or the file specified
1.4 millert 242: with the
243: .Fl f
1.22 millert 244: option) and executed.
1.4 millert 245: The working directory, the environment (except for the variables
1.7 aaron 246: .Ev TERM ,
247: .Ev TERMCAP ,
248: .Ev DISPLAY ,
1.4 millert 249: and
1.13 aaron 250: .Ev _ ) ,
1.4 millert 251: and the
252: .Ar umask
253: are retained from the time of invocation.
254: An
1.13 aaron 255: .Nm at
1.4 millert 256: or
257: .Nm batch
1.10 aaron 258: command invoked from a
1.4 millert 259: .Xr su 1
1.7 aaron 260: shell will retain the current user ID.
1.4 millert 261: The user will be mailed standard error and standard output from his
1.14 aaron 262: commands, if any.
1.22 millert 263: Mail will be sent using
1.4 millert 264: .Xr sendmail 8 .
265: If
1.13 aaron 266: .Nm at
1.10 aaron 267: is executed from a
1.4 millert 268: .Xr su 1
269: shell, the owner of the login shell will receive the mail.
270: .Pp
1.19 millert 271: For non-root users, permission to run
272: .Nm
273: is determined by the files
1.30 millert 274: .Pa /var/cron/at.allow
1.4 millert 275: and
1.30 millert 276: .Pa /var/cron/at.deny .
1.19 millert 277: .Em Note :
278: these files must be readable by group crontab (if they exist).
1.4 millert 279: .Pp
280: If the file
1.30 millert 281: .Pa /var/cron/at.allow
1.4 millert 282: exists, only usernames mentioned in it are allowed to use
283: .Nm at .
284: If
1.30 millert 285: .Pa /var/cron/at.allow
1.4 millert 286: does not exist,
1.30 millert 287: .Pa /var/cron/at.deny
1.14 aaron 288: is checked.
289: Every username not mentioned in it is then allowed to use
1.4 millert 290: .Nm at .
1.19 millert 291: If neither exists, only the superuser is allowed to run
1.4 millert 292: .Nm at .
293: .Pp
1.10 aaron 294: An empty
1.30 millert 295: .Pa /var/cron/at.deny
1.37 jmc 296: means that every user is allowed to use these commands.
1.5 marc 297: This is the default configuration.
1.42 jmc 298: .Sh FILES
299: .Bl -tag -width /var/cron/at.allow -compact
300: .It Pa /var/cron/atjobs
301: directory containing job files
302: .It Pa /var/cron/at.allow
303: allow permission control
304: .It Pa /var/cron/at.deny
305: deny permission control
306: .El
307: .Sh EXIT STATUS
1.41 jmc 308: The
309: .Nm
310: utility exits with one of the following values:
311: .Pp
1.42 jmc 312: .Bl -tag -width Ds -offset indent -compact
1.41 jmc 313: .It 0
314: Jobs were successfully submitted, removed, or listed.
315: .It \*(Gt0
316: An error occurred.
1.15 aaron 317: .El
1.1 deraadt 318: .Sh SEE ALSO
1.34 jmc 319: .Xr atq 1 ,
320: .Xr atrm 1 ,
1.1 deraadt 321: .Xr nice 1 ,
1.7 aaron 322: .Xr sh 1 ,
1.23 millert 323: .Xr touch 1 ,
1.4 millert 324: .Xr umask 2 ,
1.7 aaron 325: .Xr cron 8 ,
326: .Xr sendmail 8
1.35 jmc 327: .Sh STANDARDS
328: The
329: .Nm
330: and
331: .Nm batch
332: utilities are compliant with the
1.38 jmc 333: .St -p1003.1-2008
1.35 jmc 334: specification.
335: .Pp
336: The
337: .Nm
338: flags
339: .Op Fl bc
340: and the
341: .Nm batch
342: flags
343: .Op Fl fmq
344: are extensions to that specification.
1.39 jmc 345: .Pp
346: Behaviour for the
347: .Fl l
348: flag differs between this implementation and
349: .St -p1003.1-2008 .
1.47 ! jmc 350: .Pp
! 351: .St -p1003.1-2008
! 352: states that
! 353: .Nm batch
! 354: jobs are submitted to the queue
! 355: .Qq with no time constraints ;
! 356: this implementation permits a
! 357: .Ar timespec
! 358: argument.
! 359: The
! 360: .Sy teatime
! 361: keyword is an extension to the specification,
! 362: and this implementation does not support the
! 363: .Sy next
! 364: keyword.
1.17 aaron 365: .Sh AUTHORS
1.33 jaredy 366: .An -nosplit
1.17 aaron 367: .Nm at
1.31 jmc 368: was mostly written by
1.46 schwarze 369: .An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de .
1.31 jmc 370: The time parsing routines are by
1.46 schwarze 371: .An David Parsons Aq Mt orc@pell.chi.il.us .
1.1 deraadt 372: .Sh BUGS
1.13 aaron 373: .Nm at
1.4 millert 374: and
375: .Nm batch
376: as presently implemented are not suitable when users are competing for
377: resources.
378: If this is the case for your site, you might want to consider another
379: batch system, such as
380: .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