1.\" $OpenBSD: at.1,v 1.53 2015/11/16 16:43:06 millert 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: November 16 2015 $ 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 job ... 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 job ... 89Displays the queue of jobs which are currently awaiting execution. 90If a 91.Ar job 92argument is specified, only the specified jobs will be displayed. 93Unless the user is the superuser, only the user's own jobs will be 94displayed. 95.It Fl m 96Send mail to the user when the job has completed, even if there was no 97output. 98.It Fl q Ar queue 99Uses the specified queue. 100A queue designation consists of a single letter. 101Valid queue designations range from 102.Sy a 103to 104.Sy z 105and 106.Sy A 107to 108.Sy Z . 109The 110.Sy c 111queue is the default for 112.Nm at 113and the 114.Sy E 115queue for 116.Nm batch . 117Queues with higher letters run with increased niceness. 118If a job is submitted to a queue designated with an uppercase letter, it 119is treated as if it had been submitted to batch at that time. 120If the user specified the 121.Fl l 122option and 123.Nm at 124is given a specific queue, only jobs pending in that queue will be shown. 125.It Fl r Ar job ... 126Remove the specified job(s) from the 127.Nm at 128queue. 129.It Fl t Ar time_arg 130Specify the job time. 131The argument should be of the form 132.Oo Oo Ar cc Oc Ns Ar yy Oc Ns Ar mmddHHMM Ns Op \&. Ns Ar SS , 133where the parts of the argument represent the following: 134.Pp 135.Bl -tag -width Ds -compact -offset indent 136.It Ar ccyy 137Year. 138If yy is specified, but cc is not, 139a value for yy between 69 and 99 results in a cc value of 19. 140Otherwise, a cc value of 20 is used. 141.It Ar mm 142Month: 143a number from 1 to 12. 144.It Ar dd 145Day: 146a number from 1 to 31. 147.It Ar HH 148Hour: 149a number from 0 to 23. 150.It Ar MM 151Minute: 152a number from 0 to 59. 153.It Ar SS 154Second: 155a number from 0 to 60 156(permitting a leap second), 157preceded by a period. 158The default is 0. 159.El 160.El 161.Pp 162.Nm at 163allows some moderately complex 164.Ar timespec 165specifications. 166It accepts times of the form 167.Ar HHMM 168or 169.Ar HH:MM 170to run a job at a specific time of day. 171(If that time is already past, the next day is assumed.) 172You may also specify 173.Cm midnight , 174.Cm noon , 175or 176.Cm teatime 177(4pm) 178and you can have a time-of-day suffixed with 179.Cm AM 180or 181.Cm PM 182for running in the morning or the evening. 183You can also say what day the job will be run, 184by giving a date in the form 185.Ar \%month-name day 186with an optional 187.Ar year , 188or giving a date of the form 189.Ar dd.mm.ccyy , 190.Ar dd.mm.yy , 191.Ar mm/dd/ccyy , 192.Ar mm/dd/yy , 193.Ar mmddccyy , 194or 195.Ar mmddyy . 196.Pp 197The year may be given as two or four digits. 198If the year is given as two digits, it is taken to occur as soon as 199possible in the future, which may be in the next century -- 200unless it's last year, in which case it's considered to be 201a typo. 202.Pp 203The specification of a date must follow the specification of 204the time of day. 205You can also give times like 206.Oo Cm now Oc Cm + Ar count time-units , 207where the time-units can be 208.Cm minutes , 209.Cm hours , 210.Cm days , 211.Cm weeks , 212.Cm months , 213or 214.Cm years 215(the singular forms are also accepted). 216You can tell 217.Nm at 218to run the job today by suffixing the time with 219.Cm today 220and to run the job tomorrow by suffixing the time with 221.Cm tomorrow . 222The 223.Cm next 224keyword may be used as an alias for 225.Cm + 1 . 226.Pp 227For example, to run a job at 4pm three days from now, you would do 228.Ic at 4pm + 3 days . 229To run a job at 10:00am on July 31, you would do 230.Ic at 10am Jul 31 . 231To run a job at 1am tomorrow, you would do 232.Ic at 1am tomorrow . 233To run a job at midnight in one week's time, you would do 234.Ic at midnight next week . 235.Pp 236The 237.Nm at 238utility also supports the time format used by 239.Xr touch 1 240(see the 241.Fl t 242option). 243.Pp 244For both 245.Nm at 246and 247.Nm batch , 248commands are read from standard input (or the file specified 249with the 250.Fl f 251option) and executed. 252The working directory, the environment (except for the variables 253.Ev TERM , 254.Ev TERMCAP , 255.Ev DISPLAY , 256and 257.Ev _ ) , 258and the 259.Ar umask 260are retained from the time of invocation. 261An 262.Nm at 263or 264.Nm batch 265command invoked from a 266.Xr su 1 267shell will retain the current user ID. 268The user will be mailed standard error and standard output from his 269commands, if any. 270If 271.Nm at 272is executed from a 273.Xr su 1 274shell, the owner of the login shell will receive the mail. 275.Pp 276For non-root users, permission to run 277.Nm 278is determined by the files 279.Pa /var/cron/at.allow 280and 281.Pa /var/cron/at.deny . 282.Em Note : 283these files must be readable by group crontab (if they exist). 284.Pp 285If the file 286.Pa /var/cron/at.allow 287exists, only usernames mentioned in it are allowed to use 288.Nm at . 289If 290.Pa /var/cron/at.allow 291does not exist, 292.Pa /var/cron/at.deny 293is checked. 294Every username not mentioned in it is then allowed to use 295.Nm at . 296If neither exists, only the superuser is allowed to run 297.Nm at . 298.Pp 299An empty 300.Pa /var/cron/at.deny 301means that every user is allowed to use these commands. 302This is the default configuration. 303.Sh FILES 304.Bl -tag -width /var/cron/at.allow -compact 305.It Pa /var/cron/atjobs 306directory containing job files 307.It Pa /var/cron/at.allow 308allow permission control 309.It Pa /var/cron/at.deny 310deny permission control 311.El 312.Sh EXIT STATUS 313The 314.Nm 315utility exits with one of the following values: 316.Pp 317.Bl -tag -width Ds -offset indent -compact 318.It 0 319Jobs were successfully submitted, removed, or listed. 320.It >0 321An error occurred. 322.El 323.Sh SEE ALSO 324.Xr atq 1 , 325.Xr atrm 1 , 326.Xr nice 1 , 327.Xr sh 1 , 328.Xr touch 1 , 329.Xr umask 2 , 330.Xr cron 8 331.Sh STANDARDS 332The 333.Nm 334and 335.Nm batch 336utilities are compliant with the 337.St -p1003.1-2008 338specification. 339.Pp 340The 341.Nm 342flags 343.Op Fl bc 344and the 345.Nm batch 346flags 347.Op Fl fmq , 348as well as 349the 350.Cm teatime 351keyword, 352are extensions to that specification. 353.Pp 354.St -p1003.1-2008 355states that 356.Nm batch 357jobs are submitted to the queue 358.Qq with no time constraints ; 359this implementation permits a 360.Ar timespec 361argument. 362.Pp 363The at.allow/deny mechanism is marked by 364.St -p1003.1-2008 365as being an 366X/Open System Interfaces 367option. 368.Sh AUTHORS 369.An -nosplit 370.Nm at 371was mostly written by 372.An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de . 373The time parsing routines are by 374.An David Parsons Aq Mt orc@pell.chi.il.us . 375.Sh BUGS 376.Nm at 377and 378.Nm batch 379as presently implemented are not suitable when users are competing for 380resources. 381If this is the case for your site, you might want to consider another 382batch system, such as 383.Nm nqs . 384