summaryrefslogtreecommitdiffstats
path: root/upstream/archlinux/man1p/at.1p
diff options
context:
space:
mode:
Diffstat (limited to 'upstream/archlinux/man1p/at.1p')
-rw-r--r--upstream/archlinux/man1p/at.1p800
1 files changed, 800 insertions, 0 deletions
diff --git a/upstream/archlinux/man1p/at.1p b/upstream/archlinux/man1p/at.1p
new file mode 100644
index 00000000..946a3eea
--- /dev/null
+++ b/upstream/archlinux/man1p/at.1p
@@ -0,0 +1,800 @@
+'\" 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 .