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 . 187In these two files, a user is considered to be listed only if the user 188name has no blank or other characters before it on its line and a 189newline character immediately after the name, even at the end of 190the file. 191Other lines are ignored and may be used for comments. 192.Pp 193If 194.Pa _PERM_PATH/at.allow 195does not exist, 196.Pa _PERM_PATH/at.deny 197is checked, every username not mentioned in it is then allowed 198to use 199.Nm . 200.Pp 201If neither exists, only the superuser is allowed use of 202.Nm . 203This is the default configuration. 204.Sh IMPLEMENTATION NOTES 205Note that 206.Nm 207is implemented through the 208.Xr cron 8 209daemon by calling 210.Xr atrun 8 211every five minutes. 212This implies that the granularity of 213.Nm 214might not be optimal for every deployment. 215If a finer granularity is needed, the system crontab at 216.Pa /etc/crontab 217needs to be changed. 218.Sh OPTIONS 219.Bl -tag -width indent 220.It Fl q Ar queue 221Use the specified queue. 222A queue designation consists of a single letter; valid queue designations 223range from 224.Ar a 225to 226.Ar z 227and 228.Ar A 229to 230.Ar Z . 231The 232.Ar _DEFAULT_AT_QUEUE 233queue is the default for 234.Nm 235and the 236.Ar _DEFAULT_BATCH_QUEUE 237queue for 238.Nm batch . 239Queues with higher letters run with increased niceness. 240If a job is submitted to a queue designated with an uppercase letter, it 241is treated as if it had been submitted to batch at that time. 242If 243.Nm atq 244is given a specific queue, it will only show jobs pending in that queue. 245.It Fl m 246Send mail to the user when the job has completed even if there was no 247output. 248.It Fl f Ar file 249Read the job from 250.Ar file 251rather than standard input. 252.It Fl l 253With no arguments, list all jobs for the invoking user. 254If one or more 255job numbers are given, list only those jobs. 256.It Fl d 257Is an alias for 258.Nm atrm 259(this option is deprecated; use 260.Fl r 261instead). 262.It Fl b 263Is an alias for 264.Nm batch . 265.It Fl v 266For 267.Nm atq , 268shows completed but not yet deleted jobs in the queue; otherwise 269shows the time the job will be executed. 270.It Fl c 271Cat the jobs listed on the command line to standard output. 272.It Fl r 273Remove the specified jobs. 274.It Fl t 275Specify the job time using the \*[Px] time format. 276The argument should be in the form 277.Sm off 278.Op Oo Ar CC Oc Ar YY 279.Ar MM DD hh mm Op . Ar SS 280.Sm on 281where each pair of letters represents the following: 282.Pp 283.Bl -tag -width indent -compact -offset indent 284.It Ar CC 285The first two digits of the year (the century). 286.It Ar YY 287The second two digits of the year. 288.It Ar MM 289The month of the year, from 1 to 12. 290.It Ar DD 291the day of the month, from 1 to 31. 292.It Ar hh 293The hour of the day, from 0 to 23. 294.It Ar mm 295The minute of the hour, from 0 to 59. 296.It Ar SS 297The second of the minute, from 0 to 61. 298.El 299.Pp 300If the 301.Ar CC 302and 303.Ar YY 304letter pairs are not specified, the values default to the current 305year. 306If the 307.Ar SS 308letter pair is not specified, the value defaults to 0. 309.El 310.Sh FILES 311.Bl -tag -width _ATJOB_DIR/_LOCKFILE -compact 312.It Pa _ATJOB_DIR 313directory containing job files 314.It Pa _ATSPOOL_DIR 315directory containing output spool files 316.It Pa /var/run/utx.active 317login records 318.It Pa _PERM_PATH/at.allow 319allow permission control 320.It Pa _PERM_PATH/at.deny 321deny permission control 322.It Pa _ATJOB_DIR/_LOCKFILE 323job-creation lock file 324.El 325.Sh SEE ALSO 326.Xr nice 1 , 327.Xr sh 1 , 328.Xr umask 2 , 329.Xr atrun 8 , 330.Xr cron 8 , 331.Xr sendmail 8 332.Sh AUTHORS 333At was mostly written by 334.An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de . 335The time parsing routines are by 336.An David Parsons Aq orc@pell.chi.il.us , 337with minor enhancements by 338.An Joe Halpin Aq joe.halpin@attbi.com . 339.Sh BUGS 340If the file 341.Pa /var/run/utx.active 342is not available or corrupted, or if the user is not logged on at the 343time 344.Nm 345is invoked, the mail is sent to the userid found 346in the environment variable 347.Ev LOGNAME . 348If that is undefined or empty, the current userid is assumed. 349.Pp 350The 351.Nm at 352and 353.Nm batch 354utilities 355as presently implemented are not suitable when users are competing for 356resources. 357If this is the case, another batch system such as 358.Em nqs 359may be more suitable. 360.Pp 361Specifying a date past 2038 may not work on some systems. 362