1.\" $OpenBSD: at.1,v 1.59 2024/11/05 16:21:13 sobrado 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 5 2024 $ 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 133(matching 134.Xr touch 1 Ap s 135.Fl t 136format), 137where the parts of the argument represent the following: 138.Pp 139.Bl -tag -width Ds -compact -offset indent 140.It Ar ccyy 141Year. 142If yy is specified, but cc is not, 143a value for yy between 69 and 99 results in a cc value of 19. 144Otherwise, a cc value of 20 is used. 145.It Ar mm 146Month: 147a number from 1 to 12. 148.It Ar dd 149Day: 150a number from 1 to 31. 151.It Ar HH 152Hour: 153a number from 0 to 23. 154.It Ar MM 155Minute: 156a number from 0 to 59. 157.It Ar SS 158Second: 159a number from 0 to 60 160(permitting a leap second), 161preceded by a period. 162The default is 0. 163.El 164.It Ar timespec 165As well as the 166.Fl t 167option, 168.Nm at 169alternatively allows some moderately complex 170.Ar timespec 171specifications. 172It accepts times of the form 173.Ar HHMM 174or 175.Ar HH:MM 176to run a job at a specific time of day 177(if that time is already past, the next day is assumed). 178It is also possible to specify 179.Cm midnight , 180.Cm noon , 181.Cm now , 182or 183.Cm teatime 184(4pm), 185or have a time-of-day suffixed with 186.Cm AM 187or 188.Cm PM 189for running in the morning or the evening. 190To say what day the job will be run, 191give a date in the form 192.Ar \%month-name day 193with an optional 194.Ar year , 195or giving a date of the form 196.Ar dd.mm.ccyy , 197.Ar dd.mm.yy , 198.Ar mm/dd/ccyy , 199.Ar mm/dd/yy , 200.Ar mmddccyy , 201or 202.Ar mmddyy . 203.Pp 204The year may be given as two or four digits. 205If the year is given as two digits, it is taken to occur as soon as 206possible in the future, which may be in the next century \(em 207unless it's last year, in which case it's considered to be 208a typo. 209.Pp 210The specification of a date must follow the specification of 211the time of day. 212A time like 213.Oo Cm now Oc Cm + Ar count time-units 214may be given, 215where the time-units can be 216.Cm minutes , 217.Cm hours , 218.Cm days , 219.Cm weeks , 220.Cm months , 221or 222.Cm years 223(the singular forms are also accepted). 224To tell 225.Nm at 226to run the job today or tomorrow, 227suffix the time with 228.Cm today 229or 230.Cm tomorrow . 231The 232.Cm next 233keyword may be used as an alias for 234.Cm + 1 . 235.Pp 236For example, to run a job at 4pm three days from now, use 237.Ic at 4pm + 3 days . 238To run a job at 10:00am on July 31, use 239.Ic at 10am Jul 31 . 240To run a job at 1am tomorrow, use 241.Ic at 1am tomorrow . 242To run a job at midnight in one week's time, use 243.Ic at midnight next week . 244.El 245.Pp 246For both 247.Nm at 248and 249.Nm batch , 250commands are read from standard input (or the file specified 251with the 252.Fl f 253option) and executed. 254The working directory, the environment (except for the variables 255.Ev BASH_VERSINFO , 256.Ev DISPLAY , 257.Ev EUID , 258.Ev GROUPS , 259.Ev PPID , 260.Ev SHELLOPTS , 261.Ev SSH_AGENT_PID , 262.Ev SSH_AUTH_SOCK , 263.Ev TERM , 264.Ev TERMCAP , 265.Ev UID , 266and 267.Ev _ ) , 268and the 269.Ar umask 270are retained from the time of invocation. 271An 272.Nm at 273or 274.Nm batch 275command invoked from a 276.Xr su 1 277shell will retain the current user ID. 278The user will be mailed standard error and standard output from his 279commands, if any. 280If 281.Nm at 282is executed from a 283.Xr su 1 284shell, the owner of the login shell will receive the mail. 285.Pp 286For non-root users, permission to run 287.Nm 288is determined by the files 289.Pa /var/cron/at.allow 290and 291.Pa /var/cron/at.deny . 292.Em Note : 293these files must be readable by group crontab (if they exist). 294.Pp 295If the file 296.Pa /var/cron/at.allow 297exists, only usernames mentioned in it are allowed to use 298.Nm at . 299If 300.Pa /var/cron/at.allow 301does not exist, 302.Pa /var/cron/at.deny 303is checked. 304Every username not mentioned in it is then allowed to use 305.Nm at . 306If neither exists, only the superuser is allowed to run 307.Nm at . 308.Pp 309An empty 310.Pa /var/cron/at.deny 311means that every user is allowed to use these commands. 312This is the default configuration. 313.Sh FILES 314.Bl -tag -width /var/cron/at.allow -compact 315.It Pa /var/cron/atjobs 316directory containing job files 317.It Pa /var/cron/at.allow 318allow permission control 319.It Pa /var/cron/at.deny 320deny permission control 321.El 322.Sh EXIT STATUS 323The 324.Nm 325utility exits with one of the following values: 326.Pp 327.Bl -tag -width Ds -offset indent -compact 328.It 0 329Jobs were successfully submitted, removed, or listed. 330.It >0 331An error occurred. 332.El 333.Sh SEE ALSO 334.Xr atq 1 , 335.Xr atrm 1 , 336.Xr nice 1 , 337.Xr sh 1 , 338.Xr touch 1 , 339.Xr umask 2 , 340.Xr cron 8 341.Sh STANDARDS 342The 343.Nm 344and 345.Nm batch 346utilities are compliant with the 347.St -p1003.1-2024 348specification. 349.Pp 350The 351.Nm 352flags 353.Op Fl bc 354and the 355.Cm teatime 356.Ar timespec 357are extensions to that specification. 358.Pp 359.St -p1003.1-2024 360states that 361.Nm batch 362is equivalent to running 363.Qq Cm at -q b -m now . 364This implementation permits a 365.Ar timespec 366argument, as well as the ability to read from a file 367.Pq Fl f 368and specify a job queue 369.Pq Fl q , 370and does not send mail to the user 371.Pq Fl m 372by default. 373.Pp 374By default, 375.St -p1003.1-2024 376schedules 377.Nm at 378jobs in queue 379.Sy a 380and 381.Nm batch 382jobs in queue 383.Sy b . 384.Pp 385The at.allow/deny mechanism is marked by 386.St -p1003.1-2024 387as being an 388X/Open System Interfaces 389option. 390.Sh AUTHORS 391.An -nosplit 392.Nm at 393was mostly written by 394.An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de . 395The time parsing routines are by 396.An David Parsons Aq Mt orc@pell.chi.il.us . 397.Sh BUGS 398.Nm at 399and 400.Nm batch 401as presently implemented are not suitable when users are competing for 402resources. 403