diff options
Diffstat (limited to 'upstream/archlinux/man1p/at.1p')
-rw-r--r-- | upstream/archlinux/man1p/at.1p | 800 |
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 . |