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