1.\" $FreeBSD$ 2.Dd January 13, 2002 3.Dt "AT" 1 4.Os 5.Sh NAME 6.Nm at , 7.Nm batch , 8.Nm atq , 9.Nm atrm 10.Nd queue, examine or delete jobs for later execution 11.Sh SYNOPSIS 12.Nm at 13.Op Fl q Ar queue 14.Op Fl f Ar file 15.Op Fl mldbv 16.Ar time 17.Nm at 18.Op Fl q Ar queue 19.Op Fl f Ar file 20.Op Fl mldbv 21.Fl t 22.Sm off 23.Op Oo Ar CC Oc Ar YY 24.Ar MM DD hh mm Op . Ar SS 25.Sm on 26.Nm at 27.Fl c Ar job Op Ar job ... 28.Nm at 29.Fl l Op Ar job ... 30.Nm at 31.Fl l 32.Fl q Ar queue 33.Nm at 34.Fl r Ar job Op Ar job ... 35.Pp 36.Nm atq 37.Op Fl q Ar queue 38.Op Fl v 39.Pp 40.Nm atrm 41.Ar job 42.Op Ar job ... 43.Pp 44.Nm batch 45.Op Fl q Ar queue 46.Op Fl f Ar file 47.Op Fl mv 48.Op Ar time 49.Sh DESCRIPTION 50The 51.Nm at 52and 53.Nm batch 54utilities 55read commands from standard input or a specified file which are to 56be executed at a later time, using 57.Xr sh 1 . 58.Bl -tag -width indent 59.It Nm at 60executes commands at a specified time; 61.It Nm atq 62lists the user's pending jobs, unless the user is the superuser; in that 63case, everybody's jobs are listed; 64.It Nm atrm 65deletes jobs; 66.It Nm batch 67executes commands when system load levels permit; in other words, when the load average 68drops below _LOADAVG_MX, or the value specified in the invocation of 69.Nm atrun . 70.El 71.Pp 72The 73.Nm at 74utility allows some moderately complex 75.Ar time 76specifications. 77It accepts times of the form 78.Ar HHMM 79or 80.Ar HH:MM 81to run a job at a specific time of day. 82(If that time is already past, the next day is assumed.) 83As an alternative, the following keywords may be specified: 84.Em midnight , 85.Em noon , 86or 87.Em teatime 88(4pm) 89and time-of-day may be suffixed with 90.Em AM 91or 92.Em PM 93for running in the morning or the evening. 94The day on which the job is to be run may also be specified 95by giving a date in the form 96.Ar \%month-name day 97with an optional 98.Ar year , 99or giving a date of the forms 100.Ar DD.MM.YYYY , 101.Ar DD.MM.YY , 102.Ar MM/DD/YYYY , 103.Ar MM/DD/YY , 104.Ar MMDDYYYY , or 105.Ar MMDDYY . 106The specification of a date must follow the specification of 107the time of day. 108Time can also be specified as: 109.Op Em now 110.Em + Ar count \%time-units , 111where the time-units can be 112.Em minutes , 113.Em hours , 114.Em days , 115.Em weeks , 116.Em months 117or 118.Em years 119and 120.Nm 121may be told to run the job today by suffixing the time with 122.Em today 123and to run the job tomorrow by suffixing the time with 124.Em tomorrow . 125.Pp 126For example, to run a job at 4pm three days from now, use 127.Nm at Ar 4pm + 3 days , 128to run a job at 10:00am on July 31, use 129.Nm at Ar 10am Jul 31 130and to run a job at 1am tomorrow, use 131.Nm at Ar 1am tomorrow . 132.Pp 133The 134.Nm at 135utility also supports the 136.Tn POSIX 137time format (see 138.Fl t 139option). 140.Pp 141For both 142.Nm 143and 144.Nm batch , 145commands are read from standard input or the file specified 146with the 147.Fl f 148option and executed. 149The working directory, the environment (except for the variables 150.Ev TERM , 151.Ev TERMCAP , 152.Ev DISPLAY 153and 154.Em _ ) 155and the 156.Ar umask 157are retained from the time of invocation. 158An 159.Nm 160or 161.Nm batch 162command invoked from a 163.Xr su 1 164shell will retain the current userid. 165The user will be mailed standard error and standard output from his 166commands, if any. 167Mail will be sent using the command 168.Xr sendmail 8 . 169If 170.Nm 171is executed from a 172.Xr su 1 173shell, the owner of the login shell will receive the mail. 174.Pp 175The superuser may use these commands in any case. 176For other users, permission to use 177.Nm 178is determined by the files 179.Pa _PERM_PATH/at.allow 180and 181.Pa _PERM_PATH/at.deny . 182.Pp 183If the file 184.Pa _PERM_PATH/at.allow 185exists, only usernames mentioned in it are allowed to use 186.Nm . 187.Pp 188If 189.Pa _PERM_PATH/at.allow 190does not exist, 191.Pa _PERM_PATH/at.deny 192is checked, every username not mentioned in it is then allowed 193to use 194.Nm . 195.Pp 196If neither exists, only the superuser is allowed use of 197.Nm . 198This is the default configuration. 199.Sh IMPLEMENTATION NOTES 200Note that 201.Nm 202is implemented through the 203.Xr cron 8 204daemon by calling 205.Xr atrun 8 206every five minutes. 207This implies that the granularity of 208.Nm 209might not be optimal for every deployment. 210If a finer granularity is needed, the system crontab at 211.Pa /etc/crontab 212needs to be changed. 213.Sh OPTIONS 214.Bl -tag -width indent 215.It Fl q Ar queue 216Use the specified queue. 217A queue designation consists of a single letter; valid queue designations 218range from 219.Ar a 220to 221.Ar z 222and 223.Ar A 224to 225.Ar Z . 226The 227.Ar _DEFAULT_AT_QUEUE 228queue is the default for 229.Nm 230and the 231.Ar _DEFAULT_BATCH_QUEUE 232queue for 233.Nm batch . 234Queues with higher letters run with increased niceness. 235If a job is submitted to a queue designated with an uppercase letter, it 236is treated as if it had been submitted to batch at that time. 237If 238.Nm atq 239is given a specific queue, it will only show jobs pending in that queue. 240.It Fl m 241Send mail to the user when the job has completed even if there was no 242output. 243.It Fl f Ar file 244Read the job from 245.Ar file 246rather than standard input. 247.It Fl l 248With no arguments, list all jobs for the invoking user. 249If one or more 250job numbers are given, list only those jobs. 251.It Fl d 252Is an alias for 253.Nm atrm 254(this option is deprecated; use 255.Fl r 256instead). 257.It Fl b 258Is an alias for 259.Nm batch . 260.It Fl v 261For 262.Nm atq , 263shows completed but not yet deleted jobs in the queue; otherwise 264shows the time the job will be executed. 265.It Fl c 266Cat the jobs listed on the command line to standard output. 267.It Fl r 268Remove the specified jobs. 269.It Fl t 270Specify the job time using the \*[Px] time format. 271The argument should be in the form 272.Sm off 273.Op Oo Ar CC Oc Ar YY 274.Ar MM DD hh mm Op . Ar SS 275.Sm on 276where each pair of letters represents the following: 277.Pp 278.Bl -tag -width indent -compact -offset indent 279.It Ar CC 280The first two digits of the year (the century). 281.It Ar YY 282The second two digits of the year. 283.It Ar MM 284The month of the year, from 1 to 12. 285.It Ar DD 286the day of the month, from 1 to 31. 287.It Ar hh 288The hour of the day, from 0 to 23. 289.It Ar mm 290The minute of the hour, from 0 to 59. 291.It Ar SS 292The second of the minute, from 0 to 61. 293.El 294.Pp 295If the 296.Ar CC 297and 298.Ar YY 299letter pairs are not specified, the values default to the current 300year. 301If the 302.Ar SS 303letter pair is not specified, the value defaults to 0. 304.El 305.Sh FILES 306.Bl -tag -width _ATJOB_DIR/_LOCKFILE -compact 307.It Pa _ATJOB_DIR 308directory containing job files 309.It Pa _ATSPOOL_DIR 310directory containing output spool files 311.It Pa /var/run/utmp 312login records 313.It Pa _PERM_PATH/at.allow 314allow permission control 315.It Pa _PERM_PATH/at.deny 316deny permission control 317.It Pa _ATJOB_DIR/_LOCKFILE 318job-creation lock file 319.El 320.Sh SEE ALSO 321.Xr nice 1 , 322.Xr sh 1 , 323.Xr umask 2 , 324.Xr atrun 8 , 325.Xr cron 8 , 326.Xr sendmail 8 327.Sh BUGS 328If the file 329.Pa /var/run/utmp 330is not available or corrupted, or if the user is not logged on at the 331time 332.Nm 333is invoked, the mail is sent to the userid found 334in the environment variable 335.Ev LOGNAME . 336If that is undefined or empty, the current userid is assumed. 337.Pp 338The 339.Nm at 340and 341.Nm batch 342utilities 343as presently implemented are not suitable when users are competing for 344resources. 345If this is the case, another batch system such as 346.Em nqs 347may be more suitable. 348.Pp 349Specifying a date past 2038 may not work on some systems. 350.Sh AUTHORS 351At was mostly written by 352.An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de . 353The time parsing routines are by 354.An David Parsons Aq orc@pell.chi.il.us , 355with minor enhancements by 356.An Joe Halpin Aq joe.halpin@attbi.com . 357