1.\" $OpenBSD: at.1,v 1.55 2018/03/16 16:58:26 schwarze 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: March 16 2018 $ 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 \(em 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 BASH_VERSINFO , 254.Ev DISPLAY , 255.Ev EUID , 256.Ev GROUPS , 257.Ev PPID , 258.Ev SHELLOPTS , 259.Ev SSH_AGENT_PID , 260.Ev SSH_AUTH_SOCK , 261.Ev TERM , 262.Ev TERMCAP , 263.Ev UID , 264and 265.Ev _ ) , 266and the 267.Ar umask 268are retained from the time of invocation. 269An 270.Nm at 271or 272.Nm batch 273command invoked from a 274.Xr su 1 275shell will retain the current user ID. 276The user will be mailed standard error and standard output from his 277commands, if any. 278If 279.Nm at 280is executed from a 281.Xr su 1 282shell, the owner of the login shell will receive the mail. 283.Pp 284For non-root users, permission to run 285.Nm 286is determined by the files 287.Pa /var/cron/at.allow 288and 289.Pa /var/cron/at.deny . 290.Em Note : 291these files must be readable by group crontab (if they exist). 292.Pp 293If the file 294.Pa /var/cron/at.allow 295exists, only usernames mentioned in it are allowed to use 296.Nm at . 297If 298.Pa /var/cron/at.allow 299does not exist, 300.Pa /var/cron/at.deny 301is checked. 302Every username not mentioned in it is then allowed to use 303.Nm at . 304If neither exists, only the superuser is allowed to run 305.Nm at . 306.Pp 307An empty 308.Pa /var/cron/at.deny 309means that every user is allowed to use these commands. 310This is the default configuration. 311.Sh FILES 312.Bl -tag -width /var/cron/at.allow -compact 313.It Pa /var/cron/atjobs 314directory containing job files 315.It Pa /var/cron/at.allow 316allow permission control 317.It Pa /var/cron/at.deny 318deny permission control 319.El 320.Sh EXIT STATUS 321The 322.Nm 323utility exits with one of the following values: 324.Pp 325.Bl -tag -width Ds -offset indent -compact 326.It 0 327Jobs were successfully submitted, removed, or listed. 328.It >0 329An error occurred. 330.El 331.Sh SEE ALSO 332.Xr atq 1 , 333.Xr atrm 1 , 334.Xr nice 1 , 335.Xr sh 1 , 336.Xr touch 1 , 337.Xr umask 2 , 338.Xr cron 8 339.Sh STANDARDS 340The 341.Nm 342and 343.Nm batch 344utilities are compliant with the 345.St -p1003.1-2008 346specification. 347.Pp 348The 349.Nm 350flags 351.Op Fl bc 352and the 353.Nm batch 354flags 355.Op Fl fmq , 356as well as 357the 358.Cm teatime 359keyword, 360are extensions to that specification. 361.Pp 362.St -p1003.1-2008 363states that 364.Nm batch 365jobs are submitted to the queue 366.Qq with no time constraints ; 367this implementation permits a 368.Ar timespec 369argument. 370.Pp 371The at.allow/deny mechanism is marked by 372.St -p1003.1-2008 373as being an 374X/Open System Interfaces 375option. 376.Sh AUTHORS 377.An -nosplit 378.Nm at 379was mostly written by 380.An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de . 381The time parsing routines are by 382.An David Parsons Aq Mt orc@pell.chi.il.us . 383.Sh BUGS 384.Nm at 385and 386.Nm batch 387as presently implemented are not suitable when users are competing for 388resources. 389If this is the case for your site, you might want to consider another 390batch system, such as 391.Nm nqs . 392