1.\" $OpenBSD: at.1,v 1.45 2011/09/04 10:24:46 jmc Exp $ 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, WHETHER 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.\" 27.Dd $Mdocdate: September 4 2011 $ 28.Dt AT 1 29.Os 30.Sh NAME 31.Nm at , 32.Nm batch 33.Nd queue, examine or delete jobs for later execution 34.Sh SYNOPSIS 35.Nm at 36.Op Fl bm 37.Op Fl f Ar file 38.Op Fl l Op Ar user ... 39.Op Fl q Ar queue 40.Fl t Ar time_arg | timespec 41.Nm at 42.Fl c | r 43.Ar job ... 44.Nm batch 45.Op Fl m 46.Op Fl f Ar file 47.Op Fl q Ar queue 48.Op Ar timespec 49.Sh DESCRIPTION 50.Nm at 51and 52.Nm batch 53read commands from standard input or a specified file which 54are to be executed at a later time, via the user's shell as 55specified by the 56.Ev SHELL 57environment variable. 58If 59.Ev SHELL 60is not set, the shell in the user's password database entry is used 61instead. 62If all else fails, 63.Xr sh 1 64will be used. 65.Pp 66The related programs are as follows: 67.Bl -tag -width Ds 68.It Nm at 69Executes commands at a specified time. 70.It Nm batch 71Executes commands when system load levels permit. 72In other words, when 73the load average drops below 1.5, or the value specified in the invocation of 74.Xr cron 8 . 75.El 76.Pp 77The options are as follows: 78.Bl -tag -width indent 79.It Fl b 80An alias for 81.Nm batch . 82.It Fl c Ar job ... 83Prints the jobs listed on the command line to standard output. 84.It Fl f Ar file 85Reads the job from 86.Ar file 87rather than standard input. 88.It Fl l Op Ar user ... 89Displays the queue of jobs which are currently awaiting execution. 90If a 91.Ar user 92argument is specified, only jobs belonging to that user will 93be displayed. 94Unless the user is the superuser, only the user's own jobs will be 95displayed. 96.It Fl m 97Send mail to the user when the job has completed, even if there was no 98output. 99.It Fl q Ar queue 100Uses the specified queue. 101A queue designation consists of a single letter. 102Valid queue designations range from 103.Sy a 104to 105.Sy z 106and 107.Sy A 108to 109.Sy Z . 110The 111.Sy c 112queue is the default for 113.Nm at 114and the 115.Sy E 116queue for 117.Nm batch . 118Queues with higher letters run with increased niceness. 119If a job is submitted to a queue designated with an uppercase letter, it 120is treated as if it had been submitted to batch at that time. 121If the user specified the 122.Fl l 123option and 124.Nm at 125is given a specific queue, only jobs pending in that queue will be shown. 126.It Fl r Ar job ... 127Remove the specified job(s) from the 128.Nm at 129queue. 130.It Fl t Ar time_arg 131Specify the job time. 132The argument should be of the form 133[[cc]yy]mmddHHMM[.SS], 134where the parts of the argument represent the following: 135.Pp 136.Bl -tag -width Ds -compact -offset indent 137.It Ar ccyy 138Year. 139If yy is specified, but cc is not, 140a value for yy between 69 and 99 results in a cc value of 19. 141Otherwise, a cc value of 20 is used. 142.It Ar mm 143Month: 144a number from 1 to 12. 145.It Ar dd 146Day: 147a number from 1 to 31. 148.It Ar HH 149Hour: 150a number from 0 to 23. 151.It Ar MM 152Minute: 153a number from 0 to 59. 154.It Ar SS 155Second: 156a number from 0 to 60 157(permitting a leap second), 158preceded by a period. 159The default is 0. 160.El 161.El 162.Pp 163.Nm at 164allows some moderately complex 165.Ar timespec 166specifications. 167It accepts times of the form 168.Ar HHMM 169or 170.Ar HH:MM 171to run a job at a specific time of day. 172(If that time is already past, the next day is assumed.) 173You may also specify 174.Sy midnight , 175.Sy noon , 176or 177.Sy teatime 178(4pm) 179and you can have a time-of-day suffixed with 180.Dq AM 181or 182.Dq PM 183for running in the morning or the evening. 184You can also say what day the job will be run, 185by giving a date in the form 186.Ar \%month-name day 187with an optional 188.Ar year , 189or giving a date of the form 190.Ar dd.mm.ccyy , 191.Ar dd.mm.yy , 192.Ar mm/dd/ccyy , 193.Ar mm/dd/yy , 194.Ar mmddccyy , 195or 196.Ar mmddyy . 197.Pp 198The year may be given as two or four digits. 199If the year is given as two digits, it is taken to occur as soon as 200possible in the future, which may be in the next century -- 201unless it's last year, in which case it's considered to be 202a typo. 203.Pp 204The specification of a date must follow the specification of 205the time of day. 206You can also give times like 207.Op Sq now 208.Sy + Ar count \%time-units , 209where the time-units can be 210.Sy minutes , 211.Sy hours , 212.Sy days , 213or 214.Sy weeks 215and you can tell 216.Nm at 217to run the job today by suffixing the time with 218.Sy today 219and to run the job tomorrow by suffixing the time with 220.Sy tomorrow . 221.Pp 222For example, to run a job at 4pm three days from now, you would do 223.Ic at 4pm + 3 days . 224To run a job at 10:00am on July 31, you would do 225.Ic at 10am Jul 31 . 226To run a job at 1am tomorrow, you would do 227.Ic at 1am tomorrow . 228.Pp 229The 230.Nm at 231utility also supports the time format used by 232.Xr touch 1 233(see the 234.Fl t 235option). 236.Pp 237For both 238.Nm at 239and 240.Nm batch , 241commands are read from standard input (or the file specified 242with the 243.Fl f 244option) and executed. 245The working directory, the environment (except for the variables 246.Ev TERM , 247.Ev TERMCAP , 248.Ev DISPLAY , 249and 250.Ev _ ) , 251and the 252.Ar umask 253are retained from the time of invocation. 254An 255.Nm at 256or 257.Nm batch 258command invoked from a 259.Xr su 1 260shell will retain the current user ID. 261The user will be mailed standard error and standard output from his 262commands, if any. 263Mail will be sent using 264.Xr sendmail 8 . 265If 266.Nm at 267is executed from a 268.Xr su 1 269shell, the owner of the login shell will receive the mail. 270.Pp 271For non-root users, permission to run 272.Nm 273is determined by the files 274.Pa /var/cron/at.allow 275and 276.Pa /var/cron/at.deny . 277.Em Note : 278these files must be readable by group crontab (if they exist). 279.Pp 280If the file 281.Pa /var/cron/at.allow 282exists, only usernames mentioned in it are allowed to use 283.Nm at . 284If 285.Pa /var/cron/at.allow 286does not exist, 287.Pa /var/cron/at.deny 288is checked. 289Every username not mentioned in it is then allowed to use 290.Nm at . 291If neither exists, only the superuser is allowed to run 292.Nm at . 293.Pp 294An empty 295.Pa /var/cron/at.deny 296means that every user is allowed to use these commands. 297This is the default configuration. 298.Sh FILES 299.Bl -tag -width /var/cron/at.allow -compact 300.It Pa /var/cron/atjobs 301directory containing job files 302.It Pa /var/cron/at.allow 303allow permission control 304.It Pa /var/cron/at.deny 305deny permission control 306.El 307.Sh EXIT STATUS 308The 309.Nm 310utility exits with one of the following values: 311.Pp 312.Bl -tag -width Ds -offset indent -compact 313.It 0 314Jobs were successfully submitted, removed, or listed. 315.It \*(Gt0 316An error occurred. 317.El 318.Sh SEE ALSO 319.Xr atq 1 , 320.Xr atrm 1 , 321.Xr nice 1 , 322.Xr sh 1 , 323.Xr touch 1 , 324.Xr umask 2 , 325.Xr cron 8 , 326.Xr sendmail 8 327.Sh STANDARDS 328The 329.Nm 330and 331.Nm batch 332utilities are compliant with the 333.St -p1003.1-2008 334specification. 335.Pp 336The 337.Nm 338flags 339.Op Fl bc 340and the 341.Nm batch 342flags 343.Op Fl fmq 344are extensions to that specification. 345.Pp 346Behaviour for the 347.Fl l 348flag differs between this implementation and 349.St -p1003.1-2008 . 350.Sh AUTHORS 351.An -nosplit 352.Nm at 353was mostly written by 354.An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de . 355The time parsing routines are by 356.An David Parsons Aq orc@pell.chi.il.us . 357.Sh BUGS 358.Nm at 359and 360.Nm batch 361as presently implemented are not suitable when users are competing for 362resources. 363If this is the case for your site, you might want to consider another 364batch system, such as 365.Nm nqs . 366