Annotation of src/usr.bin/at/at.1, Revision 1.39
1.39 ! jmc 1: .\" $OpenBSD: at.1,v 1.38 2009/02/08 17:15:09 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
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.39 ! jmc 27: .Dd $Mdocdate: February 8 2009 $
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.23 millert 130: .It Fl t Ar time_arg
131: Specify the job time using the format specified by
132: .Xr touch 1 .
1.22 millert 133: The argument should be in the form
134: .Ar [[CC]YY]MMDDhhmm[.SS]
135: where each pair of letters represents the following:
136: .Pp
1.23 millert 137: .Bl -tag -width Ds -compact -offset indent
1.22 millert 138: .It Ar CC
139: The first two digits of the year (the century).
140: .It Ar YY
141: The second two digits of the year.
142: .It Ar MM
143: The month of the year, from 1 to 12.
144: .It Ar DD
145: the day of the month, from 1 to 31.
146: .It Ar hh
147: The hour of the day, from 0 to 23.
148: .It Ar mm
149: The minute of the hour, from 0 to 59.
150: .It Ar SS
151: The second of the minute, from 0 to 61.
152: .El
153: .Pp
154: If the
155: .Ar CC
156: and
157: .Ar YY
158: letter pairs are not specified, the values default to the current
159: year.
160: If the
161: .Ar SS
162: letter pair is not specified, the value defaults to 0.
1.13 aaron 163: .El
164: .Pp
165: .Nm at
1.4 millert 166: allows some moderately complex
1.23 millert 167: .Ar timespec
1.14 aaron 168: specifications.
169: It accepts times of the form
1.1 deraadt 170: .Ar HHMM
171: or
172: .Ar HH:MM
1.4 millert 173: to run a job at a specific time of day.
174: (If that time is already past, the next day is assumed.)
1.1 deraadt 175: You may also specify
1.13 aaron 176: .Sy midnight ,
177: .Sy noon ,
1.1 deraadt 178: or
1.13 aaron 179: .Sy teatime
1.4 millert 180: (4pm)
181: and you can have a time-of-day suffixed with
1.13 aaron 182: .Dq AM
1.1 deraadt 183: or
1.13 aaron 184: .Dq PM
1.4 millert 185: for running in the morning or the evening.
186: You can also say what day the job will be run,
1.1 deraadt 187: by giving a date in the form
1.4 millert 188: .Ar \%month-name day
1.1 deraadt 189: with an optional
190: .Ar year ,
191: or giving a date of the form
1.22 millert 192: .Ar DD.MM.CCYY ,
193: .Ar DD.MM.YY ,
194: .Ar MM/DD/CCYY ,
195: .Ar MM/DD/YY ,
196: .Ar MMDDCCYY ,
1.1 deraadt 197: or
1.22 millert 198: .Ar MMDDYY .
1.13 aaron 199: .Pp
200: The year may be given as two or four digits.
1.9 alex 201: If the year is given as two digits, it is taken to occur as soon as
202: possible in the future, which may be in the next century --
203: unless it's last year, in which case it's considered to be
204: a typo.
1.13 aaron 205: .Pp
1.4 millert 206: The specification of a date must follow the specification of
207: the time of day.
1.1 deraadt 208: You can also give times like
1.13 aaron 209: .Op Sq now
210: .Sy + Ar count \%time-units ,
1.4 millert 211: where the time-units can be
1.13 aaron 212: .Sy minutes ,
213: .Sy hours ,
214: .Sy days ,
1.1 deraadt 215: or
1.13 aaron 216: .Sy weeks
1.4 millert 217: and you can tell
1.13 aaron 218: .Nm at
1.4 millert 219: to run the job today by suffixing the time with
1.13 aaron 220: .Sy today
1.4 millert 221: and to run the job tomorrow by suffixing the time with
1.13 aaron 222: .Sy tomorrow .
1.4 millert 223: .Pp
224: For example, to run a job at 4pm three days from now, you would do
1.13 aaron 225: .Ic at 4pm + 3 days .
1.7 aaron 226: To run a job at 10:00am on July 31, you would do
1.13 aaron 227: .Ic at 10am Jul 31 .
1.7 aaron 228: To run a job at 1am tomorrow, you would do
1.13 aaron 229: .Ic at 1am tomorrow .
1.4 millert 230: .Pp
1.22 millert 231: The
232: .Nm at
1.23 millert 233: utility also supports the time format used by
234: .Xr touch 1
235: (see the
1.22 millert 236: .Fl t
237: option).
238: .Pp
1.4 millert 239: For both
1.13 aaron 240: .Nm at
1.4 millert 241: and
242: .Nm batch ,
1.22 millert 243: commands are read from standard input (or the file specified
1.4 millert 244: with the
245: .Fl f
1.22 millert 246: option) and executed.
1.4 millert 247: The working directory, the environment (except for the variables
1.7 aaron 248: .Ev TERM ,
249: .Ev TERMCAP ,
250: .Ev DISPLAY ,
1.4 millert 251: and
1.13 aaron 252: .Ev _ ) ,
1.4 millert 253: and the
254: .Ar umask
255: are retained from the time of invocation.
256: An
1.13 aaron 257: .Nm at
1.4 millert 258: or
259: .Nm batch
1.10 aaron 260: command invoked from a
1.4 millert 261: .Xr su 1
1.7 aaron 262: shell will retain the current user ID.
1.4 millert 263: The user will be mailed standard error and standard output from his
1.14 aaron 264: commands, if any.
1.22 millert 265: Mail will be sent using
1.4 millert 266: .Xr sendmail 8 .
267: If
1.13 aaron 268: .Nm at
1.10 aaron 269: is executed from a
1.4 millert 270: .Xr su 1
271: shell, the owner of the login shell will receive the mail.
272: .Pp
1.19 millert 273: For non-root users, permission to run
274: .Nm
275: is determined by the files
1.30 millert 276: .Pa /var/cron/at.allow
1.4 millert 277: and
1.30 millert 278: .Pa /var/cron/at.deny .
1.19 millert 279: .Em Note :
280: these files must be readable by group crontab (if they exist).
1.4 millert 281: .Pp
282: If the file
1.30 millert 283: .Pa /var/cron/at.allow
1.4 millert 284: exists, only usernames mentioned in it are allowed to use
285: .Nm at .
286: If
1.30 millert 287: .Pa /var/cron/at.allow
1.4 millert 288: does not exist,
1.30 millert 289: .Pa /var/cron/at.deny
1.14 aaron 290: is checked.
291: Every username not mentioned in it is then allowed to use
1.4 millert 292: .Nm at .
1.19 millert 293: If neither exists, only the superuser is allowed to run
1.4 millert 294: .Nm at .
295: .Pp
1.10 aaron 296: An empty
1.30 millert 297: .Pa /var/cron/at.deny
1.37 jmc 298: means that every user is allowed to use these commands.
1.5 marc 299: This is the default configuration.
1.1 deraadt 300: .Sh FILES
1.30 millert 301: .Bl -tag -width /var/cron/at.allow -compact
302: .It Pa /var/cron/atjobs
1.7 aaron 303: directory containing job files
1.30 millert 304: .It Pa /var/cron/at.allow
1.7 aaron 305: allow permission control
1.30 millert 306: .It Pa /var/cron/at.deny
1.7 aaron 307: deny permission control
1.15 aaron 308: .El
1.1 deraadt 309: .Sh SEE ALSO
1.34 jmc 310: .Xr atq 1 ,
311: .Xr atrm 1 ,
1.1 deraadt 312: .Xr nice 1 ,
1.7 aaron 313: .Xr sh 1 ,
1.23 millert 314: .Xr touch 1 ,
1.4 millert 315: .Xr umask 2 ,
1.7 aaron 316: .Xr cron 8 ,
317: .Xr sendmail 8
1.35 jmc 318: .Sh STANDARDS
319: The
320: .Nm
321: and
322: .Nm batch
323: utilities are compliant with the
1.38 jmc 324: .St -p1003.1-2008
1.35 jmc 325: specification.
326: .Pp
327: The
328: .Nm
329: flags
330: .Op Fl bc
331: and the
332: .Nm batch
333: flags
334: .Op Fl fmq
335: are extensions to that specification.
1.39 ! jmc 336: .Pp
! 337: Behaviour for the
! 338: .Fl l
! 339: flag differs between this implementation and
! 340: .St -p1003.1-2008 .
1.17 aaron 341: .Sh AUTHORS
1.33 jaredy 342: .An -nosplit
1.17 aaron 343: .Nm at
1.31 jmc 344: was mostly written by
345: .An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de .
346: The time parsing routines are by
347: .An David Parsons Aq orc@pell.chi.il.us .
1.1 deraadt 348: .Sh BUGS
1.13 aaron 349: .Nm at
1.4 millert 350: and
351: .Nm batch
352: as presently implemented are not suitable when users are competing for
353: resources.
354: If this is the case for your site, you might want to consider another
355: batch system, such as
356: .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