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