at.html

IEEE 1003.1-2003, Single Unix Specification v3

<h4><a name="tag_04_05_07"></a>INPUT FILES</h4>

<blockquote>
<p>See the STDIN section.</p>

<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
The text files <b>/usr/lib/cron/at.allow</b> and <b>/usr/lib/cron/at.deny</b> shall contain zero or more user names, one per line,
of users who are, respectively, authorized or denied access to the <i>at</i> and <a href="../utilities/batch.html"><i>batch</i></a>
utilities. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
</blockquote>

<h4><a name="tag_04_05_08"></a>ENVIRONMENT VARIABLES</h4>

<blockquote>
<p>The following environment variables shall affect the execution of <i>at</i>:</p>

<dl compact>
<dt><i>LANG</i></dt>

<dd>Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/xbd_chap08.html#tag_08_02">Section 8.2, Internationalization Variables</a> for
the precedence of internationalization variables used to determine the values of locale categories.)</dd>

<dt><i>LC_ALL</i></dt>

<dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>

<dt><i>LC_CTYPE</i></dt>

<dd>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).</dd>

<dt><i>LC_MESSAGES</i></dt>

<dd>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.</dd>

<dt><i>NLSPATH</i></dt>

<dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
Determine the location of message catalogs for the processing of <i>LC_MESSAGES .</i> <img src="../images/opt-end.gif" alt=
"[Option End]" border="0"></dd>

<dt><i>LC_TIME</i></dt>

<dd>Determine the format and contents for date and time strings written and accepted by <i>at</i>.</dd>

<dt><i>SHELL</i></dt>

<dd>Determine a name of a command interpreter to be used to invoke the at-job. If the variable is unset or null, <a href=
"../utilities/sh.html"><i>sh</i></a> shall be used. If it is set to a value other than a name for <a href=
"../utilities/sh.html"><i>sh</i></a>, the implementation shall do one of the following: use that shell; use <a href=
"../utilities/sh.html"><i>sh</i></a>; use the login shell from the user database; or any of the preceding accompanied by a warning
diagnostic about which was chosen.</dd>

<dt><i>TZ</i></dt>

<dd>Determine the timezone. The job shall be submitted for execution at the time specified by <i>timespec</i> or <b>-t</b>
<i>time</i> relative to the timezone specified by the <i>TZ</i> variable. If <i>timespec</i> specifies a timezone, it shall
override <i>TZ .</i> If <i>timespec</i> does not specify a timezone and <i>TZ</i> is unset or null, an unspecified default timezone
shall be used.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_05_09"></a>ASYNCHRONOUS EVENTS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<h4><a name="tag_04_05_10"></a>STDOUT</h4>

<blockquote>
<p>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>

<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
<b>-l</b> option:</p>

<pre>
<tt>"%s\t%s\n",</tt> <i>at_job_id</i><tt>, &lt;</tt><i>date</i><tt>&gt;
</tt>
</pre>

<p>where <i>date</i> shall be equivalent in format to the output of:</p>

<pre>
<tt>date +"%a %b %e %T %Y"
</tt>
</pre>

<p>The date and time written shall be adjusted so that they appear in the timezone of the user (as determined by the <i>TZ</i>
variable).</p>
</blockquote>

<h4><a name="tag_04_05_11"></a>STDERR</h4>

<blockquote>
<p>In the POSIX locale, the following shall be written to standard error when a job has been successfully submitted:</p>

<pre>
<tt>"job %s at %s\n",</tt> <i>at_job_id</i><tt>, &lt;</tt><i>date</i><tt>&gt;
</tt>
</pre>

<p>where <i>date</i> 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>

<p>Diagnostic messages, if any, shall be written to standard error.</p>
</blockquote>

<h4><a name="tag_04_05_12"></a>OUTPUT FILES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_05_13"></a>EXTENDED DESCRIPTION</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_05_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>The <i>at</i> utility successfully submitted, removed, or listed a job or jobs.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_05_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>The job shall not be scheduled, removed, or listed.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_05_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>The format of the <i>at</i> 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>

<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>

<p>Some implementations do not allow substitution of different shells using <i>SHELL .</i> System V systems, for example, have used
the login shell value for the user in <b>/etc/passwd</b>. To select reliably another command interpreter, the user must include it
as part of the script, such as:</p>

<pre>
<b>$</b> <tt>at 1800
myshell myscript
EOT
</tt><b>job ... at ...
$</b>
</pre>
</blockquote>

<h4><a name="tag_04_05_17"></a>EXAMPLES</h4>

<blockquote>
<ol>
<li>
<p>This sequence can be used at a terminal:</p>

<pre>
<tt>at -m 0730 tomorrow
sort &lt; file &gt;outfile
EOT
</tt>
</pre>
</li>

<li>
<p>This sequence, which demonstrates redirecting standard error to a pipe, is useful in a command procedure (the sequence of output
redirection specifications is significant):</p>

<pre>
<tt>at now + 1 hour &lt;&lt;!
diff file1 file2 2&gt;&amp;1 &gt;outfile | mailx mygroup
!
</tt>
</pre>
</li>

<li>
<p>To have a job reschedule itself, <i>at</i> can be invoked from within the at-job. For example, this daily processing script
named <b>my.daily</b> runs every day (although <a href="../utilities/crontab.html"><i>crontab</i></a> is a more appropriate vehicle
for such work):</p>

<pre>
<tt># my.daily runs every day
</tt><i>daily processing</i><tt>at now tomorrow &lt; my.daily
</tt>
</pre>
</li>

<li>
<p>The spacing of the three portions of the POSIX locale <i>timespec</i> is quite flexible as long as there are no ambiguities.
Examples of various times and operand presentation include:</p>

<pre>
<tt>at 0815am Jan 24
at 8 :15amjan24
at now "+ 1day"
at 5 pm FRIday
at '17
    utc+
    30minutes'
</tt>
</pre>
</li>
</ol>
</blockquote>

<h4><a name="tag_04_05_18"></a>RATIONALE</h4>

<blockquote>
<p>The <i>at</i> 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>

<p>The <b>-t</b> <i>time</i> option was added as a new capability to support an internationalized way of specifying a time for
execution of the submitted job.</p>

<p>Early proposals added a &quot;jobname&quot; concept as a way of giving submitted jobs names that are meaningful to the user submitting
them. The historical, system-specified <i>at_job_id</i> 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 <i>at</i> functionality is useful in simple
environments, but in large or complex situations, the functionality provided by the Batch Services option is more suitable.</p>

<p>The <b>-q</b> option historically has been an undocumented option, used mainly by the <a href=
"../utilities/batch.html"><i>batch</i></a> utility.</p>

<p>The System V <b>-m</b> 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>

<p>The behavior of <i>at</i> &lt;<b>now</b>&gt; was changed in an early proposal from being unspecified to submitting a job for
potentially immediate execution. Historical BSD <i>at</i> 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>

<p>On BSD-based systems, a <b>-u</b> <i>user</i> 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>

<p>The <b>-f</b> <i>file</i> option from System V is used instead of the BSD method of using the last operand as the pathname. The
BSD method is ambiguous-does:</p>

<pre>
<tt>at 1200 friday
</tt>
</pre>

<p>mean the same thing if there is a file named <b>friday</b> in the current directory?</p>

<p>The <i>at_job_id</i> 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>

<p>The <i>at</i> utility varies between System V and BSD systems in the way timezones are used. On System V systems, the <i>TZ</i>
variable affects the at-job submission times and the times displayed for the user. On BSD systems, <i>TZ</i> 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 <i>at</i> command immediately following an unsetting or null assignment to <i>TZ
.</i> For example:</p>

<pre>
<tt>TZ= at noon ...
</tt>
</pre>

<p>gives the desired BSD result.</p>

<p>While the <a href="../utilities/yacc.html"><i>yacc</i></a>-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 <i>day_number</i>, <i>year_number</i>, and so
on, based on the context.</p>
</blockquote>

<h4><a name="tag_04_05_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_05_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="batch.html"><i>batch</i></a> , <a href="crontab.html"><i>crontab</i></a></p>
</blockquote>

<h4><a name="tag_04_05_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 2.</p>
</blockquote>

<h4><a name="tag_04_05_22"></a>Issue 6</h4>

<blockquote>
<p>This utility is marked as part of the User Portability Utilities option.</p>

<p>The following new requirements on POSIX implementations derive from alignment with the Single UNIX Specification:</p>

<ul>
<li>
<p>If <b>-m</b> is not used, the job's standard output and standard error are provided to the user by mail.</p>
</li>
</ul>

<p>The effects of using the <b>-q</b> and <b>-t</b> options as defined in the IEEE&nbsp;P1003.2b draft standard are specified.</p>

<p>The normative text is reworded to avoid use of the term &quot;must&quot; for application requirements.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>