at.1p (21915B)
- '\" et
- .TH AT "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- at
- \(em execute commands at a later time
- .SH SYNOPSIS
- .LP
- .nf
- at \fB[\fR-m\fB] [\fR-f \fIfile\fB] [\fR-q \fIqueuename\fB] \fR-t \fItime_arg\fR
- .P
- at \fB[\fR-m\fB] [\fR-f \fIfile\fB] [\fR-q \fIqueuename\fB] \fItimespec\fR...
- .P
- at -r \fIat_job_id\fR...
- .P
- at -l -q \fIqueuename\fR
- .P
- at -l \fB[\fIat_job_id\fR...\fB]\fR
- .fi
- .SH DESCRIPTION
- The
- .IR at
- utility shall read commands from standard input and group them together
- as an
- .IR at-job ,
- to be executed at a later time.
- .P
- The at-job shall be executed in a separate invocation of the shell,
- running in a separate process group with no controlling terminal,
- except that the environment variables, current working directory,
- file creation mask, and other implementation-defined execution-time
- attributes in effect when the
- .IR at
- utility is executed shall be retained and used when the at-job is
- executed.
- .P
- When the at-job is submitted, the
- .IR at_job_id
- and scheduled time shall be written to standard error. The
- .IR at_job_id
- is an identifier that shall be a string consisting solely of
- alphanumeric characters and the
- <period>
- character. The
- .IR at_job_id
- shall be assigned by the system when the job is scheduled such that it
- uniquely identifies a particular job.
- .P
- User notification and the processing of the job's standard output and
- standard error are described under the
- .BR \-m
- option.
- .P
- Users shall be permitted to use
- .IR at
- if their name appears in the file
- .BR at.allow
- which is located in an implementation-defined directory.
- If that file does not exist, the file
- .BR at.deny ,
- which is located in an implementation-defined directory,
- shall be checked to determine whether the user shall be denied access to
- .IR at .
- If neither file exists, only a process with appropriate privileges
- shall be allowed to submit a job. If only
- .BR at.deny
- exists and is empty, global usage shall be permitted. The
- .BR at.allow
- and
- .BR at.deny
- files shall consist of one user name per line.
- .SH OPTIONS
- The
- .IR at
- utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 12.2" ", " "Utility Syntax Guidelines".
- .P
- The following options shall be supported:
- .IP "\fB\-f\ \fIfile\fR" 10
- Specify the pathname of a file to be used as the source of the at-job,
- instead of standard input.
- .IP "\fB\-l\fP" 10
- (The letter ell.) Report all jobs scheduled for the invoking user if no
- .IR at_job_id
- operands are specified. If
- .IR at_job_id s
- are specified, report only information for these jobs. The output shall
- be written to standard output.
- .IP "\fB\-m\fP" 10
- Send mail to the invoking user after the at-job has run, announcing its
- completion. Standard output and standard error produced by the at-job
- shall be mailed to the user as well, unless redirected elsewhere. Mail
- shall be sent even if the job produces no output.
- .RS 10
- .P
- If
- .BR \-m
- is not used, the job's standard output and standard error shall be
- provided to the user by means of mail, unless they are redirected
- elsewhere; if there is no such output to provide, the implementation
- need not notify the user of the job's completion.
- .RE
- .IP "\fB\-q\ \fIqueuename\fR" 10
- .br
- Specify in which queue to schedule a job for submission. When used with
- the
- .BR \-l
- option, limit the search to that particular queue. By default, at-jobs
- shall be scheduled in queue
- .IR a .
- In contrast, queue
- .IR b
- shall be reserved for batch jobs; see
- .IR batch .
- The meanings of all other
- .IR queuename s
- are implementation-defined. If
- .BR \-q
- is specified along with either of the
- .BR \-t
- .IR time_arg
- or
- .IR timespec
- arguments, the results are unspecified.
- .IP "\fB\-r\fP" 10
- Remove the jobs with the specified
- .IR at_job_id
- operands that were previously scheduled by the
- .IR at
- utility.
- .IP "\fB\-t\ \fItime_arg\fR" 10
- Submit the job to be run at the time specified by the
- .IR time
- option-argument, which the application shall ensure has the format as
- specified by the
- .IR touch
- .BR \-t
- .IR time
- utility.
- .SH OPERANDS
- The following operands shall be supported:
- .IP "\fIat_job_id\fR" 10
- The name reported by a previous invocation of the
- .IR at
- utility at the time the job was scheduled.
- .IP "\fItimespec\fR" 10
- Submit the job to be run at the date and time specified. All of the
- .IR timespec
- operands are interpreted as if they were separated by
- <space>
- characters and concatenated, and shall be parsed as described in the
- grammar at the end of this section. The date and time shall be interpreted
- as being in the timezone of the user (as determined by the
- .IR TZ
- variable), unless a timezone name appears as part of
- .IR time ,
- below.
- .RS 10
- .P
- In the POSIX locale, the following describes the three parts of the
- time specification string. All of the values from the
- .IR LC_TIME
- categories in the POSIX locale shall be recognized in a
- case-insensitive manner.
- .IP "\fItime\fR" 10
- The time can be specified as one, two, or four digits. One-digit and
- two-digit numbers shall be taken to be hours; four-digit numbers to be
- hours and minutes. The time can alternatively be specified as two
- numbers separated by a
- <colon>,
- meaning \fIhour\fP:\fIminute\fR. An AM/PM indication (one of the values
- from the
- .BR am_pm
- keywords in the
- .IR LC_TIME
- locale category) can follow the time; otherwise, a 24-hour clock time
- shall be understood. A timezone name can also follow to further qualify
- the time. The acceptable timezone names are implementation-defined,
- except that they shall be case-insensitive and the string
- .BR utc
- is supported to indicate the time is in Coordinated Universal Time.
- In the POSIX locale, the
- .IR time
- field can also be one of the following tokens:
- .RS 10
- .IP "\fBmidnight\fR" 10
- Indicates the time 12:00 am (00:00).
- .IP "\fBnoon\fR" 10
- Indicates the time 12:00 pm.
- .IP "\fBnow\fR" 10
- Indicates the current day and time. Invoking
- .IR at
- <\fBnow\fR> shall submit an at-job for potentially immediate execution
- (that is, subject only to unspecified scheduling delays).
- .RE
- .IP "\fIdate\fR" 10
- An optional
- .IR date
- can be specified as either a month name (one of the values from the
- .BR mon
- or
- .BR abmon
- keywords in the
- .IR LC_TIME
- locale category) followed by a day number (and possibly year number
- preceded by a comma), or a day of the week (one of the values from the
- .BR day
- or
- .BR abday
- keywords in the
- .IR LC_TIME
- locale category). In the POSIX locale, two special days shall be
- recognized:
- .RS 10
- .IP "\fBtoday\fR" 10
- Indicates the current day.
- .IP "\fBtomorrow\fR" 10
- Indicates the day following the current day.
- .P
- If no
- .IR date
- is given,
- .BR today
- shall be assumed if the given time is greater than the current time,
- and
- .BR tomorrow
- shall be assumed if it is less. If the given month is less than the
- current month (and no year is given), next year shall be assumed.
- .RE
- .IP "\fIincrement\fR" 10
- The optional
- .IR increment
- shall be a number preceded by a
- <plus-sign>
- (\c
- .BR '\(pl' )
- and suffixed by one of the following:
- .BR minutes ,
- .BR hours ,
- .BR days ,
- .BR weeks ,
- .BR months ,
- or
- .BR years .
- (The singular forms shall also be accepted.) The keyword
- .BR next
- shall be equivalent to an increment number of +1. For example, the
- following are equivalent commands:
- .RS 10
- .sp
- .RS 4
- .nf
- at 2pm + 1 week
- at 2pm next week
- .fi
- .P
- .RE
- .RE
- .RE
- .P
- The following grammar describes the precise format of
- .IR timespec
- in the POSIX locale. The general conventions for this style of grammar
- are described in
- .IR "Section 1.3" ", " "Grammar Conventions".
- This formal syntax shall take precedence over the preceding text syntax
- description. The longest possible token or delimiter shall be
- recognized at a given point. When used in a
- .IR timespec ,
- white space shall also delimit tokens.
- .sp
- .RS 4
- .nf
- %token hr24clock_hr_min
- %token hr24clock_hour
- /*
- An hr24clock_hr_min is a one, two, or four-digit number. A one-digit
- or two-digit number constitutes an hr24clock_hour. An hr24clock_hour
- may be any of the single digits [0,9], or may be double digits, ranging
- from [00,23]. If an hr24clock_hr_min is a four-digit number, the
- first two digits shall be a valid hr24clock_hour, while the last two
- represent the number of minutes, from [00,59].
- */
- .P
- %token wallclock_hr_min
- %token wallclock_hour
- /*
- A wallclock_hr_min is a one, two-digit, or four-digit number.
- A one-digit or two-digit number constitutes a wallclock_hour.
- A wallclock_hour may be any of the single digits [1,9], or may
- be double digits, ranging from [01,12]. If a wallclock_hr_min
- is a four-digit number, the first two digits shall be a valid
- wallclock_hour, while the last two represent the number of
- minutes, from [00,59].
- */
- .P
- %token minute
- /*
- A minute is a one or two-digit number whose value can be [0,9]
- or [00,59].
- */
- .P
- %token day_number
- /*
- A day_number is a number in the range appropriate for the particular
- month and year specified by month_name and year_number, respectively.
- If no year_number is given, the current year is assumed if the given
- date and time are later this year. If no year_number is given and
- the date and time have already occurred this year and the month is
- not the current month, next year is the assumed year.
- */
- .P
- %token year_number
- /*
- A year_number is a four-digit number representing the year A.D., in
- which the at_job is to be run.
- */
- .P
- %token inc_number
- /*
- The inc_number is the number of times the succeeding increment
- period is to be added to the specified date and time.
- */
- .P
- %token timezone_name
- /*
- The name of an optional timezone suffix to the time field, in an
- implementation-defined format.
- */
- .P
- %token month_name
- /*
- One of the values from the mon or abmon keywords in the LC_TIME
- locale category.
- */
- .P
- %token day_of_week
- /*
- One of the values from the day or abday keywords in the LC_TIME
- locale category.
- */
- .P
- %token am_pm
- /*
- One of the values from the am_pm keyword in the LC_TIME locale
- category.
- */
- .P
- %start timespec
- %%
- timespec : time
- | time date
- | time increment
- | time date increment
- | nowspec
- ;
- .P
- nowspec : "now"
- | "now" increment
- ;
- .P
- time : hr24clock_hr_min
- | hr24clock_hr_min timezone_name
- | hr24clock_hour ":" minute
- | hr24clock_hour ":" minute timezone_name
- | wallclock_hr_min am_pm
- | wallclock_hr_min am_pm timezone_name
- | wallclock_hour ":" minute am_pm
- | wallclock_hour ":" minute am_pm timezone_name
- | "noon"
- | "midnight"
- ;
- .P
- date : month_name day_number
- | month_name day_number "," year_number
- | day_of_week
- | "today"
- | "tomorrow"
- ;
- .P
- increment : "+" inc_number inc_period
- | "next" inc_period
- ;
- .P
- inc_period : "minute" | "minutes"
- | "hour" | "hours"
- | "day" | "days"
- | "week" | "weeks"
- | "month" | "months"
- | "year" | "years"
- ;
- .fi
- .P
- .RE
- .SH STDIN
- The standard input shall be a text file consisting of commands
- acceptable to the shell command language described in
- .IR "Chapter 2" ", " "Shell Command Language".
- The standard input shall only be used if no
- .BR \-f
- .IR file
- option is specified.
- .SH "INPUT FILES"
- See the STDIN section.
- .P
- The text files
- .BR at.allow
- and
- .BR at.deny ,
- which are located in an implementation-defined directory,
- shall contain zero or more user names, one per line, of users who are,
- respectively, authorized or denied access to the
- .IR at
- and
- .IR batch
- utilities.
- .SH "ENVIRONMENT VARIABLES"
- The following environment variables shall affect the execution of
- .IR at :
- .IP "\fILANG\fP" 10
- Provide a default value for the internationalization variables that are
- unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
- .IR "Section 8.2" ", " "Internationalization Variables"
- for the precedence of internationalization variables used to determine
- the values of locale categories.)
- .IP "\fILC_ALL\fP" 10
- If set to a non-empty string value, override the values of all the
- other internationalization variables.
- .IP "\fILC_CTYPE\fP" 10
- Determine the locale for the interpretation of sequences of bytes of
- text data as characters (for example, single-byte as opposed to
- multi-byte characters in arguments and input files).
- .IP "\fILC_MESSAGES\fP" 10
- .br
- Determine the locale that should be used to affect the format and
- contents of diagnostic messages written to standard error and
- informative messages written to standard output.
- .IP "\fINLSPATH\fP" 10
- Determine the location of message catalogs for the processing of
- .IR LC_MESSAGES .
- .IP "\fILC_TIME\fP" 10
- Determine the format and contents for date and time strings written and
- accepted by
- .IR at .
- .IP "\fISHELL\fP" 10
- Determine a name of a command interpreter to be used to invoke the
- at-job. If the variable is unset or null,
- .IR sh
- shall be used. If it is set to a value other than a name for
- .IR sh ,
- the implementation shall do one of the following: use that shell; use
- .IR sh ;
- use the login shell from the user database; or any of the preceding
- accompanied by a warning diagnostic about which was chosen.
- .IP "\fITZ\fP" 10
- Determine the timezone. The job shall be submitted for execution at the
- time specified by
- .IR timespec
- or
- .BR \-t
- .IR time
- relative to the timezone specified by the
- .IR TZ
- variable. If
- .IR timespec
- specifies a timezone, it shall override
- .IR TZ .
- If
- .IR timespec
- does not specify a timezone and
- .IR TZ
- is unset or null, an unspecified default timezone shall be used.
- .SH "ASYNCHRONOUS EVENTS"
- Default.
- .SH STDOUT
- When standard input is a terminal, prompts of unspecified format for
- each line of the user input described in the STDIN section may be
- written to standard output.
- .P
- In the POSIX locale, the following shall be written to the standard
- output for each job when jobs are listed in response to the
- .BR \-l
- option:
- .sp
- .RS 4
- .nf
- "%s\et%s\en", \fIat_job_id\fR, <\fIdate\fR>
- .fi
- .P
- .RE
- .P
- where
- .IR date
- shall be equivalent in format to the output of:
- .sp
- .RS 4
- .nf
- date +"%a %b %e %T %Y"
- .fi
- .P
- .RE
- .P
- The date and time written shall be adjusted so that they appear in the
- timezone of the user (as determined by the
- .IR TZ
- variable).
- .SH STDERR
- In the POSIX locale, the following shall be written to standard error
- when a job has been successfully submitted:
- .sp
- .RS 4
- .nf
- "job %s at %s\en", \fIat_job_id\fR, <\fIdate\fR>
- .fi
- .P
- .RE
- .P
- where
- .IR date
- has the same format as that described in the STDOUT section. Neither
- this, nor warning messages concerning the selection of the command
- interpreter, shall be considered a diagnostic that changes the exit
- status.
- .P
- Diagnostic messages, if any, shall be written to standard error.
- .SH "OUTPUT FILES"
- None.
- .SH "EXTENDED DESCRIPTION"
- None.
- .SH "EXIT STATUS"
- The following exit values shall be returned:
- .IP "\00" 6
- The
- .IR at
- utility successfully submitted, removed, or listed a job or jobs.
- .IP >0 6
- An error occurred.
- .SH "CONSEQUENCES OF ERRORS"
- The job shall not be scheduled, removed, or listed.
- .LP
- .IR "The following sections are informative."
- .SH "APPLICATION USAGE"
- The format of the
- .IR at
- command line shown here is guaranteed only for the POSIX locale. Other
- cultures may be supported with substantially different interfaces,
- although implementations are encouraged to provide comparable levels of
- functionality.
- .P
- Since the commands run in a separate shell invocation, running in a
- separate process group with no controlling terminal, open file
- descriptors, traps, and priority inherited from the invoking
- environment are lost.
- .P
- Some implementations do not allow substitution of different shells
- using
- .IR SHELL .
- System V systems, for example, have used the login shell value for the
- user in
- .BR /etc/passwd .
- To select reliably another command interpreter, the user must include
- it as part of the script, such as:
- .sp
- .RS 4
- .nf
- \fB$\fR at 1800
- myshell myscript
- EOT
- \fBjob ... at ...
- \fB$\fR
- .fi
- .P
- .RE
- .SH EXAMPLES
- .IP " 1." 4
- This sequence can be used at a terminal:
- .RS 4
- .sp
- .RS 4
- .nf
- at -m 0730 tomorrow
- sort < file >outfile
- EOT
- .fi
- .P
- .RE
- .RE
- .IP " 2." 4
- This sequence, which demonstrates redirecting standard error to a pipe,
- is useful in a command procedure (the sequence of output redirection
- specifications is significant):
- .RS 4
- .sp
- .RS 4
- .nf
- at now + 1 hour <<!
- diff file1 file2 2>&1 >outfile | mailx mygroup
- !
- .fi
- .P
- .RE
- .RE
- .IP " 3." 4
- To have a job reschedule itself,
- .IR at
- can be invoked from within the at-job. For example, this daily
- processing script named
- .BR my.daily
- runs every day (although
- .IR crontab
- is a more appropriate vehicle for such work):
- .RS 4
- .sp
- .RS 4
- .nf
- # my.daily runs every day
- \fIdaily processing\fR
- at now tomorrow < my.daily
- .fi
- .P
- .RE
- .RE
- .IP " 4." 4
- The spacing of the three portions of the POSIX locale
- .IR timespec
- is quite flexible as long as there are no ambiguities. Examples of
- various times and operand presentation include:
- .RS 4
- .sp
- .RS 4
- .nf
- at 0815am Jan 24
- at 8 :15amjan24
- at now "+ 1day"
- at 5 pm FRIday
- at \(aq17
- utc+
- 30minutes\(aq
- .fi
- .P
- .RE
- .RE
- .SH RATIONALE
- The
- .IR at
- utility reads from standard input the commands to be executed at a
- later time. It may be useful to redirect standard output and standard
- error within the specified commands.
- .P
- The
- .BR \-t
- .IR time
- option was added as a new capability to support an internationalized
- way of specifying a time for execution of the submitted job.
- .P
- Early proposals added a ``jobname'' concept as a way of giving
- submitted jobs names that are meaningful to the user submitting them.
- The historical, system-specified
- .IR at_job_id
- gives no indication of what the job is. Upon further reflection, it was
- decided that the benefit of this was not worth the change in historical
- interface. The
- .IR at
- functionality is useful in simple environments, but in large or complex
- situations, the functionality provided by the Batch Services option is
- more suitable.
- .P
- The
- .BR \-q
- option historically has been an undocumented option, used mainly by the
- .IR batch
- utility.
- .P
- The System V
- .BR \-m
- option was added to provide a method for informing users that an at-job
- had completed. Otherwise, users are only informed when output to
- standard error or standard output are not redirected.
- .P
- The behavior of
- .IR at
- <\fBnow\fP> was changed in an early proposal from being unspecified to
- submitting a job for potentially immediate execution. Historical BSD
- .IR at
- implementations support this. Historical System V implementations give
- an error in that case, but a change to the System V versions should
- have no backwards-compatibility ramifications.
- .P
- On BSD-based systems, a
- .BR \-u
- .IR user
- option has allowed those with appropriate privileges to access the work
- of other users. Since this is primarily a system administration feature
- and is not universally implemented, it has been omitted. Similarly, a
- specification for the output format for a user with appropriate
- privileges viewing the queues of other users has been omitted.
- .P
- The
- .BR \-f
- .IR file
- option from System V is used instead of the BSD method of using the
- last operand as the pathname. The BSD method is ambiguous\(emdoes:
- .sp
- .RS 4
- .nf
- at 1200 friday
- .fi
- .P
- .RE
- .P
- mean the same thing if there is a file named
- .BR friday
- in the current directory?
- .P
- The
- .IR at_job_id
- is composed of a limited character set in historical practice, and it
- is mandated here to invalidate systems that might try using characters
- that require shell quoting or that could not be easily parsed by shell
- scripts.
- .P
- The
- .IR at
- utility varies between System V and BSD systems in the way timezones
- are used. On System V systems, the
- .IR TZ
- variable affects the at-job submission times and the times displayed
- for the user. On BSD systems,
- .IR TZ
- is not taken into account. The BSD behavior is easily achieved with
- the current specification. If the user wishes to have the timezone
- default to that of the system, they merely need to issue the
- .IR at
- command immediately following an unsetting or null assignment to
- .IR TZ .
- For example:
- .sp
- .RS 4
- .nf
- TZ= at noon ...
- .fi
- .P
- .RE
- .P
- gives the desired BSD result.
- .P
- While the
- .IR yacc -like
- grammar specified in the OPERANDS section is lexically unambiguous with
- respect to the digit strings, a lexical analyzer would probably be
- written to look for and return digit strings in those cases. The parser
- could then check whether the digit string returned is a valid
- .IR day_number ,
- .IR year_number ,
- and so on, based on the context.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "\fIbatch\fR\^",
- .IR "\fIcrontab\fR\^"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 8" ", " "Environment Variables",
- .IR "Section 12.2" ", " "Utility Syntax Guidelines"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .