1AT(1P) POSIX Programmer's Manual AT(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 at — execute commands at a later time
13
15 at [-m] [-f file] [-q queuename] -t time_arg
16 at [-m] [-f file] [-q queuename] timespec...
18 at -r at_job_id...
20 at -l -q queuename
22 at -l [at_job_id...]
24
26 The at utility shall read commands from standard input and group them
27 together as an at-job, to be executed at a later time.
28 The at-job shall be executed in a separate invocation of the shell,
30 running in a separate process group with no controlling terminal,
31 except that the environment variables, current working directory, file
32 creation mask, and other implementation-defined execution-time
33 attributes in effect when the at utility is executed shall be retained
34 and used when the at-job is executed.
35 When the at-job is submitted, the at_job_id and scheduled time shall be
37 written to standard error. The at_job_id is an identifier that shall be
38 a string consisting solely of alphanumeric characters and the <period>
39 character. The at_job_id shall be assigned by the system when the job
40 is scheduled such that it uniquely identifies a particular job.
41 User notification and the processing of the job's standard output and
43 standard error are described under the -m option.
44 Users shall be permitted to use at if their name appears in the file
46 at.allow which is located in an implementation-defined directory. If
47 that file does not exist, the file at.deny, which is located in an
48 implementation-defined directory, shall be checked to determine whether
49 the user shall be denied access to at. If neither file exists, only a
50 process with appropriate privileges shall be allowed to submit a job.
51 If only at.deny exists and is empty, global usage shall be permitted.
52 The at.allow and at.deny files shall consist of one user name per line.
53
55 The at utility shall conform to the Base Definitions volume of
56 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
57 The following options shall be supported:
59 -f file Specify the pathname of a file to be used as the source of
61 the at-job, instead of standard input.
62 -l (The letter ell.) Report all jobs scheduled for the invoking
64 user if no at_job_id operands are specified. If at_job_ids
65 are specified, report only information for these jobs. The
66 output shall be written to standard output.
67 -m Send mail to the invoking user after the at-job has run,
69 announcing its completion. Standard output and standard error
70 produced by the at-job shall be mailed to the user as well,
71 unless redirected elsewhere. Mail shall be sent even if the
72 job produces no output.
73 If -m is not used, the job's standard output and standard
75 error shall be provided to the user by means of mail, unless
76 they are redirected elsewhere; if there is no such output to
77 provide, the implementation need not notify the user of the
78 job's completion.
79 -q queuename
81 Specify in which queue to schedule a job for submission. When
82 used with the -l option, limit the search to that particular
83 queue. By default, at-jobs shall be scheduled in queue a. In
84 contrast, queue b shall be reserved for batch jobs; see
85 batch. The meanings of all other queuenames are implementa‐
86 tion-defined. If -q is specified along with either of the -t
87 time_arg or timespec arguments, the results are unspecified.
88 -r Remove the jobs with the specified at_job_id operands that
90 were previously scheduled by the at utility.
91 -t time_arg
93 Submit the job to be run at the time specified by the time
94 option-argument, which the application shall ensure has the
95 format as specified by the touch -t time utility.
96
98 The following operands shall be supported:
99 at_job_id The name reported by a previous invocation of the at utility
101 at the time the job was scheduled.
102 timespec Submit the job to be run at the date and time specified. All
104 of the timespec operands are interpreted as if they were sep‐
105 arated by <space> characters and concatenated, and shall be
106 parsed as described in the grammar at the end of this sec‐
107 tion. The date and time shall be interpreted as being in the
108 timezone of the user (as determined by the TZ variable),
109 unless a timezone name appears as part of time, below.
110 In the POSIX locale, the following describes the three parts
112 of the time specification string. All of the values from the
113 LC_TIME categories in the POSIX locale shall be recognized in
114 a case-insensitive manner.
115 time The time can be specified as one, two, or four dig‐
117 its. One-digit and two-digit numbers shall be taken
118 to be hours; four-digit numbers to be hours and
119 minutes. The time can alternatively be specified as
120 two numbers separated by a <colon>, meaning
121 hour:minute. An AM/PM indication (one of the values
122 from the am_pm keywords in the LC_TIME locale cate‐
123 gory) can follow the time; otherwise, a 24-hour
124 clock time shall be understood. A timezone name can
125 also follow to further qualify the time. The
126 acceptable timezone names are implementation-
127 defined, except that they shall be case-insensitive
128 and the string utc is supported to indicate the
129 time is in Coordinated Universal Time. In the
130 POSIX locale, the time field can also be one of the
131 following tokens:
132 midnight Indicates the time 12:00 am (00:00).
134 noon Indicates the time 12:00 pm.
136 now Indicates the current day and time.
138 Invoking at <now> shall submit an at-job
139 for potentially immediate execution (that
140 is, subject only to unspecified schedul‐
141 ing delays).
142 date An optional date can be specified as either a month
144 name (one of the values from the mon or abmon key‐
145 words in the LC_TIME locale category) followed by a
146 day number (and possibly year number preceded by a
147 comma), or a day of the week (one of the values
148 from the day or abday keywords in the LC_TIME
149 locale category). In the POSIX locale, two special
150 days shall be recognized:
151 today Indicates the current day.
153 tomorrow Indicates the day following the current
155 day.
156 If no date is given, today shall be assumed if the
158 given time is greater than the current time, and
159 tomorrow shall be assumed if it is less. If the
160 given month is less than the current month (and no
161 year is given), next year shall be assumed.
162 increment The optional increment shall be a number preceded
164 by a <plus-sign> ('+') and suffixed by one of the
165 following: minutes, hours, days, weeks, months, or
166 years. (The singular forms shall also be
167 accepted.) The keyword next shall be equivalent to
168 an increment number of +1. For example, the follow‐
169 ing are equivalent commands:
170 at 2pm + 1 week
173 at 2pm next week
174 The following grammar describes the precise format of timespec in the
176 POSIX locale. The general conventions for this style of grammar are
177 described in Section 1.3, Grammar Conventions. This formal syntax
178 shall take precedence over the preceding text syntax description. The
179 longest possible token or delimiter shall be recognized at a given
180 point. When used in a timespec, white space shall also delimit tokens.
181 %token hr24clock_hr_min
184 %token hr24clock_hour
185 /*
186 An hr24clock_hr_min is a one, two, or four-digit number. A one-digit
187 or two-digit number constitutes an hr24clock_hour. An hr24clock_hour
188 may be any of the single digits [0,9], or may be double digits, ranging
189 from [00,23]. If an hr24clock_hr_min is a four-digit number, the
190 first two digits shall be a valid hr24clock_hour, while the last two
191 represent the number of minutes, from [00,59].
192 */
193 %token wallclock_hr_min
195 %token wallclock_hour
196 /*
197 A wallclock_hr_min is a one, two-digit, or four-digit number.
198 A one-digit or two-digit number constitutes a wallclock_hour.
199 A wallclock_hour may be any of the single digits [1,9], or may
200 be double digits, ranging from [01,12]. If a wallclock_hr_min
201 is a four-digit number, the first two digits shall be a valid
202 wallclock_hour, while the last two represent the number of
203 minutes, from [00,59].
204 */
205 %token minute
207 /*
208 A minute is a one or two-digit number whose value can be [0,9]
209 or [00,59].
210 */
211 %token day_number
213 /*
214 A day_number is a number in the range appropriate for the particular
215 month and year specified by month_name and year_number, respectively.
216 If no year_number is given, the current year is assumed if the given
217 date and time are later this year. If no year_number is given and
218 the date and time have already occurred this year and the month is
219 not the current month, next year is the assumed year.
220 */
221 %token year_number
223 /*
224 A year_number is a four-digit number representing the year A.D., in
225 which the at_job is to be run.
226 */
227 %token inc_number
229 /*
230 The inc_number is the number of times the succeeding increment
231 period is to be added to the specified date and time.
232 */
233 %token timezone_name
235 /*
236 The name of an optional timezone suffix to the time field, in an
237 implementation-defined format.
238 */
239 %token month_name
241 /*
242 One of the values from the mon or abmon keywords in the LC_TIME
243 locale category.
244 */
245 %token day_of_week
247 /*
248 One of the values from the day or abday keywords in the LC_TIME
249 locale category.
250 */
251 %token am_pm
253 /*
254 One of the values from the am_pm keyword in the LC_TIME locale
255 category.
256 */
257 %start timespec
259 %%
260 timespec : time
261 | time date
262 | time increment
263 | time date increment
264 | nowspec
265 ;
266 nowspec : "now"
268 | "now" increment
269 ;
270 time : hr24clock_hr_min
272 | hr24clock_hr_min timezone_name
273 | hr24clock_hour ":" minute
274 | hr24clock_hour ":" minute timezone_name
275 | wallclock_hr_min am_pm
276 | wallclock_hr_min am_pm timezone_name
277 | wallclock_hour ":" minute am_pm
278 | wallclock_hour ":" minute am_pm timezone_name
279 | "noon"
280 | "midnight"
281 ;
282 date : month_name day_number
284 | month_name day_number "," year_number
285 | day_of_week
286 | "today"
287 | "tomorrow"
288 ;
289 increment : "+" inc_number inc_period
291 | "next" inc_period
292 ;
293 inc_period : "minute" | "minutes"
295 | "hour" | "hours"
296 | "day" | "days"
297 | "week" | "weeks"
298 | "month" | "months"
299 | "year" | "years"
300 ;
301
303 The standard input shall be a text file consisting of commands accept‐
304 able to the shell command language described in Chapter 2, Shell Com‐
305 mand Language. The standard input shall only be used if no -f file
306 option is specified.
307
309 See the STDIN section.
310 The text files at.allow and at.deny, which are located in an implemen‐
312 tation-defined directory, shall contain zero or more user names, one
313 per line, of users who are, respectively, authorized or denied access
314 to the at and batch utilities.
315
317 The following environment variables shall affect the execution of at:
318 LANG Provide a default value for the internationalization vari‐
320 ables that are unset or null. (See the Base Definitions vol‐
321 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
322 ables for the precedence of internationalization variables
323 used to determine the values of locale categories.)
324 LC_ALL If set to a non-empty string value, override the values of
326 all the other internationalization variables.
327 LC_CTYPE Determine the locale for the interpretation of sequences of
329 bytes of text data as characters (for example, single-byte as
330 opposed to multi-byte characters in arguments and input
331 files).
332 LC_MESSAGES
334 Determine the locale that should be used to affect the format
335 and contents of diagnostic messages written to standard error
336 and informative messages written to standard output.
337 NLSPATH Determine the location of message catalogs for the processing
339 of LC_MESSAGES.
340 LC_TIME Determine the format and contents for date and time strings
342 written and accepted by at.
343 SHELL Determine a name of a command interpreter to be used to
345 invoke the at-job. If the variable is unset or null, sh shall
346 be used. If it is set to a value other than a name for sh,
347 the implementation shall do one of the following: use that
348 shell; use sh; use the login shell from the user database; or
349 any of the preceding accompanied by a warning diagnostic
350 about which was chosen.
351 TZ Determine the timezone. The job shall be submitted for execu‐
353 tion at the time specified by timespec or -t time relative to
354 the timezone specified by the TZ variable. If timespec speci‐
355 fies a timezone, it shall override TZ. If timespec does not
356 specify a timezone and TZ is unset or null, an unspecified
357 default timezone shall be used.
358
360 Default.
361
363 When standard input is a terminal, prompts of unspecified format for
364 each line of the user input described in the STDIN section may be writ‐
365 ten to standard output.
366 In the POSIX locale, the following shall be written to the standard
368 output for each job when jobs are listed in response to the -l option:
369 "%s\t%s\n", at_job_id, <date>
372 where date shall be equivalent in format to the output of:
374 date +"%a %b %e %T %Y"
377 The date and time written shall be adjusted so that they appear in the
379 timezone of the user (as determined by the TZ variable).
380
382 In the POSIX locale, the following shall be written to standard error
383 when a job has been successfully submitted:
384 "job %s at %s\n", at_job_id, <date>
387 where date has the same format as that described in the STDOUT section.
389 Neither this, nor warning messages concerning the selection of the com‐
390 mand interpreter, shall be considered a diagnostic that changes the
391 exit status.
392 Diagnostic messages, if any, shall be written to standard error.
394
396 None.
397
399 None.
400
402 The following exit values shall be returned:
403 0 The at utility successfully submitted, removed, or listed a job
405 or jobs.
406 >0 An error occurred.
408
410 The job shall not be scheduled, removed, or listed.
411 The following sections are informative.
413
415 The format of the at command line shown here is guaranteed only for the
416 POSIX locale. Other cultures may be supported with substantially dif‐
417 ferent interfaces, although implementations are encouraged to provide
418 comparable levels of functionality.
419 Since the commands run in a separate shell invocation, running in a
421 separate process group with no controlling terminal, open file descrip‐
422 tors, traps, and priority inherited from the invoking environment are
423 lost.
424 Some implementations do not allow substitution of different shells
426 using SHELL. System V systems, for example, have used the login shell
427 value for the user in /etc/passwd. To select reliably another command
428 interpreter, the user must include it as part of the script, such as:
429 $ at 1800
432 myshell myscript
433 EOT
434 job ... at ...
435 $
436
438 1. This sequence can be used at a terminal:
439 at -m 0730 tomorrow
442 sort < file >outfile
443 EOT
444 2. This sequence, which demonstrates redirecting standard error to a
446 pipe, is useful in a command procedure (the sequence of output re‐
447 direction specifications is significant):
448 at now + 1 hour <<!
451 diff file1 file2 2>&1 >outfile | mailx mygroup
452 !
453 3. To have a job reschedule itself, at can be invoked from within the
455 at-job. For example, this daily processing script named my.daily
456 runs every day (although crontab is a more appropriate vehicle for
457 such work):
458 # my.daily runs every day
461 daily processing
462 at now tomorrow < my.daily
463 4. The spacing of the three portions of the POSIX locale timespec is
465 quite flexible as long as there are no ambiguities. Examples of
466 various times and operand presentation include:
467 at 0815am Jan 24
470 at 8 :15amjan24
471 at now "+ 1day"
472 at 5 pm FRIday
473 at '17
474 utc+
475 30minutes'
476
478 The at utility reads from standard input the commands to be executed at
479 a later time. It may be useful to redirect standard output and standard
480 error within the specified commands.
481 The -t time option was added as a new capability to support an interna‐
483 tionalized way of specifying a time for execution of the submitted job.
484 Early proposals added a ``jobname'' concept as a way of giving submit‐
486 ted jobs names that are meaningful to the user submitting them. The
487 historical, system-specified at_job_id gives no indication of what the
488 job is. Upon further reflection, it was decided that the benefit of
489 this was not worth the change in historical interface. The at function‐
490 ality is useful in simple environments, but in large or complex situa‐
491 tions, the functionality provided by the Batch Services option is more
492 suitable.
493 The -q option historically has been an undocumented option, used mainly
495 by the batch utility.
496 The System V -m option was added to provide a method for informing
498 users that an at-job had completed. Otherwise, users are only informed
499 when output to standard error or standard output are not redirected.
500 The behavior of at <now> was changed in an early proposal from being
502 unspecified to submitting a job for potentially immediate execution.
503 Historical BSD at implementations support this. Historical System V
504 implementations give an error in that case, but a change to the System
505 V versions should have no backwards-compatibility ramifications.
506 On BSD-based systems, a -u user option has allowed those with appropri‐
508 ate privileges to access the work of other users. Since this is primar‐
509 ily a system administration feature and is not universally implemented,
510 it has been omitted. Similarly, a specification for the output format
511 for a user with appropriate privileges viewing the queues of other
512 users has been omitted.
513 The -f file option from System V is used instead of the BSD method of
515 using the last operand as the pathname. The BSD method is ambiguous—
516 does:
517 at 1200 friday
520 mean the same thing if there is a file named friday in the current
522 directory?
523 The at_job_id is composed of a limited character set in historical
525 practice, and it is mandated here to invalidate systems that might try
526 using characters that require shell quoting or that could not be easily
527 parsed by shell scripts.
528 The at utility varies between System V and BSD systems in the way time‐
530 zones are used. On System V systems, the TZ variable affects the at-job
531 submission times and the times displayed for the user. On BSD systems,
532 TZ is not taken into account. The BSD behavior is easily achieved with
533 the current specification. If the user wishes to have the timezone
534 default to that of the system, they merely need to issue the at command
535 immediately following an unsetting or null assignment to TZ. For exam‐
536 ple:
537 TZ= at noon ...
540 gives the desired BSD result.
542 While the yacc-like grammar specified in the OPERANDS section is lexi‐
544 cally unambiguous with respect to the digit strings, a lexical analyzer
545 would probably be written to look for and return digit strings in those
546 cases. The parser could then check whether the digit string returned is
547 a valid day_number, year_number, and so on, based on the context.
548
550 None.
551
553 batch, crontab
554 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
556 Variables, Section 12.2, Utility Syntax Guidelines
557
559 Portions of this text are reprinted and reproduced in electronic form
560 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
561 table Operating System Interface (POSIX), The Open Group Base Specifi‐
562 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
563 Electrical and Electronics Engineers, Inc and The Open Group. In the
564 event of any discrepancy between this version and the original IEEE and
565 The Open Group Standard, the original IEEE and The Open Group Standard
566 is the referee document. The original Standard can be obtained online
567 at http://www.opengroup.org/unix/online.html .
568 Any typographical or formatting errors that appear in this page are
570 most likely to have been introduced during the conversion of the source
571 files to man page format. To report such errors, see https://www.ker‐
572 nel.org/doc/man-pages/reporting_bugs.html .
573IEEE/The Open Group 2017 AT(1P)