1AT(1P)                     POSIX Programmer's Manual                    AT(1P)
2
3
4

PROLOG

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

NAME

12       at — execute commands at a later time
13

SYNOPSIS

15       at [-m] [-f file] [-q queuename] -t time_arg
16
17       at [-m] [-f file] [-q queuename] timespec...
18
19       at -r at_job_id...
20
21       at -l -q queuename
22
23       at -l [at_job_id...]
24

DESCRIPTION

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
29       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
36       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
42       User notification and the processing of the job's standard  output  and
43       standard error are described under the -m option.
44
45       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

OPTIONS

55       The at  utility  shall  conform  to  the  Base  Definitions  volume  of
56       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
57
58       The following options shall be supported:
59
60       -f file   Specify  the  pathname  of a file to be used as the source of
61                 the at-job, instead of standard input.
62
63       -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
68       -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
74                 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
80       -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
89       -r        Remove  the  jobs  with the specified at_job_id operands that
90                 were previously scheduled by the at utility.
91
92       -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

OPERANDS

98       The following operands shall be supported:
99
100       at_job_id The name reported by a previous invocation of the at  utility
101                 at the time the job was scheduled.
102
103       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
111                 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
116                 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
133                           midnight  Indicates the time 12:00 am (00:00).
134
135                           noon      Indicates the time 12:00 pm.
136
137                           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
143                 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
152                           today     Indicates the current day.
153
154                           tomorrow  Indicates the day following  the  current
155                                     day.
156
157                           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
163                 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
171
172                               at 2pm + 1 week
173                               at 2pm next week
174
175       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
182
183           %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
194           %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
206           %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
212           %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
222           %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
228           %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
234           %token timezone_name
235           /*
236             The name of an optional timezone suffix to the time field, in an
237             implementation-defined format.
238           */
239
240           %token month_name
241           /*
242             One of the values from the mon or abmon keywords in the LC_TIME
243             locale category.
244           */
245
246           %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
252           %token am_pm
253           /*
254             One of the values from the am_pm keyword in the LC_TIME locale
255             category.
256           */
257
258           %start timespec
259           %%
260           timespec    : time
261                       | time date
262                       | time increment
263                       | time date increment
264                       | nowspec
265                       ;
266
267           nowspec     : "now"
268                       | "now" increment
269                       ;
270
271           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
283           date        : month_name day_number
284                       | month_name day_number "," year_number
285                       | day_of_week
286                       | "today"
287                       | "tomorrow"
288                       ;
289
290           increment   : "+" inc_number inc_period
291                       | "next" inc_period
292                       ;
293
294           inc_period  : "minute" | "minutes"
295                       | "hour" | "hours"
296                       | "day" | "days"
297                       | "week" | "weeks"
298                       | "month" | "months"
299                       | "year" | "years"
300                       ;
301

STDIN

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

INPUT FILES

309       See the STDIN section.
310
311       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

ENVIRONMENT VARIABLES

317       The following environment variables shall affect the execution of at:
318
319       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
325       LC_ALL    If set to a non-empty string value, override  the  values  of
326                 all the other internationalization variables.
327
328       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
333       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
338       NLSPATH   Determine the location of message catalogs for the processing
339                 of LC_MESSAGES.
340
341       LC_TIME   Determine  the  format and contents for date and time strings
342                 written and accepted by at.
343
344       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
352       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

ASYNCHRONOUS EVENTS

360       Default.
361

STDOUT

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
367       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
370
371           "%s\t%s\n", at_job_id, <date>
372
373       where date shall be equivalent in format to the output of:
374
375
376           date +"%a %b %e %T %Y"
377
378       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

STDERR

382       In  the  POSIX locale, the following shall be written to standard error
383       when a job has been successfully submitted:
384
385
386           "job %s at %s\n", at_job_id, <date>
387
388       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
393       Diagnostic messages, if any, shall be written to standard error.
394

OUTPUT FILES

396       None.
397

EXTENDED DESCRIPTION

399       None.
400

EXIT STATUS

402       The following exit values shall be returned:
403
404        0    The  at  utility successfully submitted, removed, or listed a job
405             or jobs.
406
407       >0    An error occurred.
408

CONSEQUENCES OF ERRORS

410       The job shall not be scheduled, removed, or listed.
411
412       The following sections are informative.
413

APPLICATION USAGE

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
420       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
425       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
430
431           $ at 1800
432           myshell myscript
433           EOT
434           job ... at ...
435           $
436

EXAMPLES

438        1. This sequence can be used at a terminal:
439
440
441               at -m 0730 tomorrow
442               sort < file >outfile
443               EOT
444
445        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
449
450               at now + 1 hour <<!
451               diff file1 file2 2>&1 >outfile | mailx mygroup
452               !
453
454        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
459
460               # my.daily runs every day
461               daily processing
462               at now tomorrow < my.daily
463
464        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
468
469               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

RATIONALE

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
482       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
485       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
494       The -q option historically has been an undocumented option, used mainly
495       by the batch utility.
496
497       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
501       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
507       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
514       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
518
519           at 1200 friday
520
521       mean the same thing if there is a file  named  friday  in  the  current
522       directory?
523
524       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
529       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
538
539           TZ= at noon ...
540
541       gives the desired BSD result.
542
543       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

FUTURE DIRECTIONS

550       None.
551

SEE ALSO

553       batch, crontab
554
555       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
569       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 .
573
574
575
576IEEE/The Open Group                  2017                               AT(1P)
Impressum