Annotation of src/usr.bin/at/at.1, Revision 1.13
1.13 ! aaron 1: .\" $OpenBSD: at.1,v 1.12 1999/09/14 05:28:23 deraadt Exp $
1.4 millert 2: .\" $FreeBSD: at.man,v 1.6 1997/02/22 19:54:05 peter Exp $
3: .Dd April 12, 1995
1.7 aaron 4: .Dt AT 1
1.3 michaels 5: .Os
1.1 deraadt 6: .Sh NAME
1.11 aaron 7: .Nm at ,
8: .Nm atq ,
9: .Nm atrm ,
10: .Nm batch
1.4 millert 11: .Nd queue, examine or delete jobs for later execution
1.1 deraadt 12: .Sh SYNOPSIS
13: .Nm at
1.4 millert 14: .Op Fl V
1.1 deraadt 15: .Op Fl q Ar queue
16: .Op Fl f Ar file
1.4 millert 17: .Op Fl mldbv
1.1 deraadt 18: .Ar time
1.4 millert 19: .Nm at
20: .Op Fl V
21: .Fl c Ar job Op Ar job ...
1.1 deraadt 22: .Nm atq
1.4 millert 23: .Op Fl V
1.1 deraadt 24: .Op Fl q Ar queue
25: .Op Fl v
26: .Nm atrm
1.4 millert 27: .Op Fl V
1.1 deraadt 28: .Ar job
29: .Op Ar job ...
30: .Nm batch
1.4 millert 31: .Op Fl V
32: .Op Fl q Ar queue
1.1 deraadt 33: .Op Fl f Ar file
1.4 millert 34: .Op Fl mv
35: .Op Ar time
1.1 deraadt 36: .Sh DESCRIPTION
1.13 ! aaron 37: .Nm at
1.1 deraadt 38: and
39: .Nm batch
1.4 millert 40: read commands from standard input or a specified file which
41: are to be executed at a later time, using
1.1 deraadt 42: .Xr sh 1 .
1.13 ! aaron 43: .Pp
! 44: The related programs are as follows:
1.1 deraadt 45: .Bl -tag -width indent
46: .It Nm at
47: Executes commands at a specified time.
48: .It Nm atq
1.13 ! aaron 49: Lists the user's pending jobs, unless the user is the super-user.
1.7 aaron 50: In that case, all users' jobs are listed.
1.1 deraadt 51: .It Nm atrm
52: Deletes jobs.
53: .It Nm batch
1.4 millert 54: Executes commands when system load levels permit. In other words, when
55: the load average drops below 1.5, or the value specified in the invocation of
56: .Nm atrun .
1.1 deraadt 57: .El
58: .Pp
1.13 ! aaron 59: The options are as follows:
! 60: .Bl -tag -width indent
! 61: .It Fl V
! 62: Prints the version number to standard error.
! 63: .It Fl q Ar queue
! 64: Uses the specified queue.
! 65: A queue designation consists of a single letter. Valid queue designations
! 66: range from
! 67: .Sy a
! 68: to
! 69: .Sy z
! 70: and
! 71: .Sy A
! 72: to
! 73: .Sy Z .
! 74: The
! 75: .Sy c
! 76: queue is the default for
! 77: .Nm at
! 78: and the
! 79: .Sy E
! 80: queue for
! 81: .Nm batch .
! 82: Queues with higher letters run with increased niceness.
! 83: If a job is submitted to a queue designated with an uppercase letter, it
! 84: is treated as if it had been submitted to batch at that time.
! 85: If
! 86: .Nm atq
! 87: is given a specific queue, it will only show jobs pending in that queue.
! 88: .It Fl m
! 89: Send mail to the user when the job has completed, even if there was no
! 90: output.
! 91: .It Fl f Ar file
! 92: Reads the job from
! 93: .Ar file
! 94: rather than standard input.
! 95: .It Fl l
! 96: An alias for
! 97: .Nm atq .
! 98: .It Fl d
! 99: An alias for
! 100: .Nm atrm .
! 101: .It Fl b
! 102: An alias for
! 103: .Nm batch .
! 104: .It Fl v
! 105: For
! 106: .Nm atq ,
! 107: shows completed but not yet deleted jobs in the queue. Otherwise
! 108: shows the time the job will be executed.
! 109: .It Fl c
! 110: Prints the jobs listed on the command line to standard output.
! 111: .El
! 112: .Pp
! 113: .Nm at
1.4 millert 114: allows some moderately complex
115: .Ar time
116: specifications. It accepts times of the form
1.1 deraadt 117: .Ar HHMM
118: or
119: .Ar HH:MM
1.4 millert 120: to run a job at a specific time of day.
121: (If that time is already past, the next day is assumed.)
1.1 deraadt 122: You may also specify
1.13 ! aaron 123: .Sy midnight ,
! 124: .Sy noon ,
1.1 deraadt 125: or
1.13 ! aaron 126: .Sy teatime
1.4 millert 127: (4pm)
128: and you can have a time-of-day suffixed with
1.13 ! aaron 129: .Dq AM
1.1 deraadt 130: or
1.13 ! aaron 131: .Dq PM
1.4 millert 132: for running in the morning or the evening.
133: You can also say what day the job will be run,
1.1 deraadt 134: by giving a date in the form
1.4 millert 135: .Ar \%month-name day
1.1 deraadt 136: with an optional
137: .Ar year ,
138: or giving a date of the form
1.7 aaron 139: .Ar MMDDYY ,
1.1 deraadt 140: .Ar MM/DD/YY
141: or
142: .Ar DD.MM.YY .
1.13 ! aaron 143: .Pp
! 144: The year may be given as two or four digits.
1.9 alex 145: If the year is given as two digits, it is taken to occur as soon as
146: possible in the future, which may be in the next century --
147: unless it's last year, in which case it's considered to be
148: a typo.
1.13 ! aaron 149: .Pp
1.4 millert 150: The specification of a date must follow the specification of
151: the time of day.
1.1 deraadt 152: You can also give times like
1.13 ! aaron 153: .Op Sq now
! 154: .Sy + Ar count \%time-units ,
1.4 millert 155: where the time-units can be
1.13 ! aaron 156: .Sy minutes ,
! 157: .Sy hours ,
! 158: .Sy days ,
1.1 deraadt 159: or
1.13 ! aaron 160: .Sy weeks
1.4 millert 161: and you can tell
1.13 ! aaron 162: .Nm at
1.4 millert 163: to run the job today by suffixing the time with
1.13 ! aaron 164: .Sy today
1.4 millert 165: and to run the job tomorrow by suffixing the time with
1.13 ! aaron 166: .Sy tomorrow .
1.4 millert 167: .Pp
168: For example, to run a job at 4pm three days from now, you would do
1.13 ! aaron 169: .Ic at 4pm + 3 days .
1.7 aaron 170: To run a job at 10:00am on July 31, you would do
1.13 ! aaron 171: .Ic at 10am Jul 31 .
1.7 aaron 172: To run a job at 1am tomorrow, you would do
1.13 ! aaron 173: .Ic at 1am tomorrow .
1.4 millert 174: .Pp
175: For both
1.13 ! aaron 176: .Nm at
1.4 millert 177: and
178: .Nm batch ,
179: commands are read from standard input or the file specified
180: with the
181: .Fl f
182: option and executed.
183: The working directory, the environment (except for the variables
1.7 aaron 184: .Ev TERM ,
185: .Ev TERMCAP ,
186: .Ev DISPLAY ,
1.4 millert 187: and
1.13 ! aaron 188: .Ev _ ) ,
1.4 millert 189: and the
190: .Ar umask
191: are retained from the time of invocation.
192: An
1.13 ! aaron 193: .Nm at
1.4 millert 194: or
195: .Nm batch
1.10 aaron 196: command invoked from a
1.4 millert 197: .Xr su 1
1.7 aaron 198: shell will retain the current user ID.
1.4 millert 199: The user will be mailed standard error and standard output from his
200: commands, if any. Mail will be sent using the command
201: .Xr sendmail 8 .
202: If
1.13 ! aaron 203: .Nm at
1.10 aaron 204: is executed from a
1.4 millert 205: .Xr su 1
206: shell, the owner of the login shell will receive the mail.
207: .Pp
1.13 ! aaron 208: The super-user may use these commands in any case.
1.4 millert 209: For other users, permission to use at is determined by the files
210: .Pa /var/at/at.allow
211: and
212: .Pa /var/at/at.deny .
213: .Pp
214: If the file
215: .Pa /var/at/at.allow
216: exists, only usernames mentioned in it are allowed to use
217: .Nm at .
218: If
219: .Pa /var/at/at.allow
220: does not exist,
221: .Pa /var/at/at.deny
1.7 aaron 222: is checked. Every username not mentioned in it is then allowed
1.4 millert 223: to use
224: .Nm at .
1.13 ! aaron 225: If neither exists, only the super-user is allowed use of
1.4 millert 226: .Nm at .
227: .Pp
1.10 aaron 228: An empty
1.4 millert 229: .Pa /var/at/at.deny
230: means that every user is allowed use these commands.
1.5 marc 231: This is the default configuration.
1.13 ! aaron 232: .Pp
1.1 deraadt 233: .Sh FILES
1.4 millert 234: .Bl -tag -width /var/at/.lockfile -compact
1.1 deraadt 235: .It Pa /var/at/jobs
1.7 aaron 236: directory containing job files
1.1 deraadt 237: .It Pa /var/at/spool
1.7 aaron 238: directory containing output spool files
1.4 millert 239: .It Pa /var/run/utmp
1.7 aaron 240: login records
1.4 millert 241: .It Pa /var/at/at.allow
1.7 aaron 242: allow permission control
1.4 millert 243: .It Pa /var/at/at.deny
1.7 aaron 244: deny permission control
1.4 millert 245: .It Pa /var/at/.lockfile
1.7 aaron 246: job-creation lock file
1.1 deraadt 247: .Sh SEE ALSO
248: .Xr nice 1 ,
1.7 aaron 249: .Xr sh 1 ,
1.4 millert 250: .Xr umask 2 ,
1.7 aaron 251: .Xr atrun 8 ,
252: .Xr cron 8 ,
253: .Xr sendmail 8
1.1 deraadt 254: .Sh BUGS
255: If the file
256: .Pa /var/run/utmp
1.4 millert 257: is not available or corrupted, or if the user is not logged on at the
1.10 aaron 258: time
1.13 ! aaron 259: .Nm at
1.7 aaron 260: is invoked, the mail is sent to the user ID found
1.4 millert 261: in the environment variable
1.7 aaron 262: .Ev LOGNAME .
263: If that is undefined or empty, the current user ID is assumed.
1.4 millert 264: .Pp
1.13 ! aaron 265: .Nm at
1.4 millert 266: and
267: .Nm batch
268: as presently implemented are not suitable when users are competing for
269: resources.
270: If this is the case for your site, you might want to consider another
271: batch system, such as
272: .Nm nqs .
1.12 deraadt 273: .Pp
274: .Nm atq
275: always prints the year as two digits. Since
276: .Nm at
277: only permits submission of jobs in the future, it is somewhat
278: clear which century the job will run in.
1.4 millert 279: .Sh AUTHORS
1.13 ! aaron 280: .Nm at
1.7 aaron 281: was mostly written by Thomas Koenig <ig25@rz.uni-karlsruhe.de>.
1.4 millert 282: The time parsing routines are by David Parsons <orc@pell.chi.il.us>.