2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
25 .\" This notice shall appear on any product containing this material.
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
43 .\" Copyright 1989 AT&T
44 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Portions Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
47 .TH AT 1 "Apr 13, 2005"
49 at, batch \- execute commands at a later time
53 \fB/usr/bin/at\fR [\fB-c\fR | \fB-k\fR | \fB-s\fR] [\fB-m\fR] [\fB-f\fR \fIfile\fR] [\fB-p\fR \fIproject\fR]
54 [\fB-q\fR \fIqueuename\fR] \fB-t\fR \fItime\fR
59 \fB/usr/bin/at\fR [\fB-c\fR | \fB-k\fR | \fB-s\fR] [\fB-m\fR] [\fB-f\fR \fIfile\fR] [\fB-p\fR \fIproject\fR]
60 [\fB-q\fR \fIqueuename\fR] \fItimespec\fR...
65 \fB/usr/bin/at\fR \fB-l\fR [\fB-p\fR \fIproject\fR] [\fB-q\fR \fIqueuename\fR] [\fIat_job_id\fR \fI...\fR]
70 \fB/usr/bin/at\fR \fB-r\fR \fIat_job_id\fR \fI...\fR
75 \fB/usr/bin/batch\fR [\fB-p\fR \fIproject\fR]
80 \fB/usr/xpg4/bin/at\fR [\fB-c\fR | \fB-k\fR | \fB-s\fR] [\fB-m\fR] [\fB-f\fR \fIfile\fR] [\fB-p\fR \fIproject\fR]
81 [\fB-q\fR \fIqueuename\fR] \fB-t\fR \fItime\fR
86 \fB/usr/xpg4/bin/at\fR [\fB-c\fR | \fB-k\fR | \fB-s\fR] [\fB-m\fR] [\fB-f\fR \fIfile\fR] [\fB-p\fR \fIproject\fR]
87 [\fB-q\fR \fIqueuename\fR] \fItimespec\fR...
92 \fB/usr/xpg4/bin/at\fR \fB-l\fR [\fB-p\fR \fIproject\fR] [\fB-q\fR \fIqueuename\fR]
93 [\fIat_job_id\fR \fI...\fR]
98 \fB/usr/xpg4/bin/at\fR \fB-r\fR \fIat_job_id\fR \fI...\fR
103 \fB/usr/xpg4/bin/batch\fR [\fB-p\fR \fIproject\fR]
110 The \fBat\fR utility reads commands from standard input and groups them
111 together as an \fIat-job\fR, to be executed at a later time.
114 The at-job is executed in a separate invocation of the shell, running in a
115 separate process group with no controlling terminal, except that the
116 environment variables, current working directory, file creation mask (see
117 \fBumask\fR(1)), and system resource limits (for \fBsh\fR and \fBksh\fR only,
118 see \fBulimit\fR(1)) in effect when the \fBat\fR utility is executed is
119 retained and used when the at-job is executed.
122 When the at-job is submitted, the \fIat_job_id\fR and scheduled time are
123 written to standard error. The \fIat_job_id\fR is an identifier that is a
124 string consisting solely of alphanumeric characters and the period character.
125 The \fIat_job_id\fR is assigned by the system when the job is scheduled such
126 that it uniquely identifies a particular job.
129 User notification and the processing of the job's standard output and standard
130 error are described under the \fB-m\fR option.
133 Users are permitted to use \fBat\fR and \fBbatch\fR (see below) if their name
134 appears in the file \fB/usr/lib/cron/at.allow\fR. If that file does not exist,
135 the file \fB/usr/lib/cron/at.deny\fR is checked to determine if the user should
136 be denied access to \fBat\fR. If neither file exists, only a user with the
137 \fBsolaris.jobs.user\fR authorization is allowed to submit a job. If only
138 \fBat.deny\fR exists and is empty, global usage is permitted. The
139 \fBat.allow\fR and \fBat.deny\fR files consist of one user name per line.
142 \fBcron\fR and \fBat\fR jobs are not be executed if the user's account is
143 locked. Only accounts which are not locked as defined in \fBshadow\fR(4) will
144 have their job or process executed.
148 The \fBbatch\fR utility reads commands to be executed at a later time.
151 Commands of the forms:
155 /usr/bin/batch [-p project]
156 /usr/xpg4/bin/batch [-p project]
163 are respectively equivalent to:
167 /usr/bin/at -q b [-p project] now
168 /usr/xpg4/bin/at -q b -m [-p project] now
175 where queue \fBb\fR is a special \fBat\fR queue, specifically for batch jobs.
176 Batch jobs are submitted to the batch queue for immediate execution. Execution
177 of submitted jobs can be delayed by limits on the number of jobs allowed to run
178 concurrently. See \fBqueuedefs\fR(4).
182 If the \fB-c\fR, \fB-k\fR, or \fB-s\fR options are not specified, the
183 \fBSHELL\fR environment variable by default determines which shell to use.
186 If \fBSHELL\fR is unset or \fBNULL\fR, \fB/usr/bin/sh\fR is used.
189 The following options are supported:
196 C shell. \fBcsh\fR(1) is used to execute the at-job.
205 Korn shell. \fBksh\fR(1) is used to execute the at-job.
214 Bourne shell. \fBsh\fR(1) is used to execute the at-job.
220 \fB\fB-f\fR \fIfile\fR \fR
223 Specifies the path of a file to be used as the source of the at-job, instead of
233 (The letter ell.) Reports all jobs scheduled for the invoking user if no
234 \fIat_job_id\fR operands are specified. If \fIat_job_id\fRs are specified,
235 reports only information for these jobs.
244 Sends mail to the invoking user after the at-job has run, announcing its
245 completion. Standard output and standard error produced by the at-job are
246 mailed to the user as well, unless redirected elsewhere. Mail is sent even if
247 the job produces no output.
249 If \fB-m\fR is not used, the job's standard output and standard error is
250 provided to the user by means of mail, unless they are redirected elsewhere; if
251 there is no such output to provide, the user is not notified of the job's
258 \fB\fB-p\fR \fIproject\fR\fR
261 Specifies under which project the \fBat\fR or \fBbatch\fR job is run. When used
262 with the \fB-l\fR option, limits the search to that particular project. Values
263 for \fIproject\fR is interpreted first as a project name, and then as a
264 possible project \fBID\fR, if entirely numeric. By default, the user's current
271 \fB\fB-q\fR \fIqueuename\fR \fR
274 Specifies in which queue to schedule a job for submission. When used with the
275 \fB-l\fR option, limits the search to that particular queue. Values for
276 \fIqueuename\fR are limited to the lower case letters \fBa\fR through \fBz\fR.
277 By default, at-jobs are scheduled in queue \fBa\fR. In contrast, queue \fBb\fR
278 is reserved for batch jobs. Since queue \fBc\fR is reserved for cron jobs, it
279 can not be used with the \fB-q\fR option.
285 \fB\fB-r\fR \fIat_job_id\fR \fR
288 Removes the jobs with the specified \fIat_job_id\fR operands that were
289 previously scheduled by the \fBat\fR utility.
295 \fB\fB-t\fR \fItime\fR \fR
298 Submits the job to be run at the time specified by the \fItime\fR
299 option-argument, which must have the format as specified by the \fBtouch\fR(1)
306 The following operands are supported:
310 \fB\fIat_job_id\fR \fR
313 The name reported by a previous invocation of the \fBat\fR utility at the time
314 the job was scheduled.
320 \fB\fItimespec\fR \fR
323 Submit the job to be run at the date and time specified. All of the
324 \fItimespec\fR operands are interpreted as if they were separated by space
325 characters and concatenated. The date and time are interpreted as being in the
326 timezone of the user (as determined by the \fBTZ\fR variable), unless a
327 timezone name appears as part of \fItime\fR below.
329 In the "C" locale, the following describes the three parts of the time
330 specification string. All of the values from the \fBLC_TIME\fR categories in
331 the "C" locale are recognized in a case-insensitive manner.
338 The \fItime\fR can be specified as one, two or four digits. One- and two-digit
339 numbers are taken to be hours, four-digit numbers to be hours and minutes. The
340 time can alternatively be specified as two numbers separated by a colon,
341 meaning \fIhour\fR\fB:\fR\fIminute\fR. An AM/PM indication (one of the values
342 from the \fBam_pm\fR keywords in the \fBLC_TIME\fR locale category) can follow
343 the time; otherwise, a 24-hour clock time is understood. A timezone name of
344 \fBGMT\fR, \fBUCT\fR, or \fBZULU \fR(case insensitive) can follow to specify
345 that the time is in Coordinated Universal Time. Other timezones can be
346 specified using the \fBTZ\fR environment variable. The \fItime\fR field can
347 also be one of the following tokens in the "C" locale:
351 \fB\fBmidnight\fR \fR
354 Indicates the time 12:00 am (00:00).
363 Indicates the time 12:00 pm.
372 Indicate the current day and time. Invoking \fBat\fR \fBnow\fR submits an
373 at-job for potentially immediate execution (that is, subject only to
374 unspecified scheduling delays).
385 An optional \fIdate\fR can be specified as either a month name (one of the
386 values from the \fBmon\fR or \fBabmon\fR keywords in the \fBLC_TIME\fR locale
387 category) followed by a day number (and possibly year number preceded by a
388 comma) or a day of the week (one of the values from the \fBday\fR or
389 \fBabday\fR keywords in the \fBLC_TIME\fR locale category). Two special days
390 are recognized in the "C" locale:
397 Indicates the current day.
403 \fB\fBtomorrow\fR \fR
406 Indicates the day following the current day.
409 If no \fIdate\fR is given, \fBtoday\fR is assumed if the given time is greater
410 than the current time, and \fBtomorrow\fR is assumed if it is less. If the
411 given month is less than the current month (and no year is given), next year is
418 \fB\fIincrement\fR \fR
421 The optional \fIincrement\fR is a number preceded by a plus sign (\fB+\fR) and
422 suffixed by one of the following: \fBminutes\fR, \fBhours\fR, \fBdays\fR,
423 \fBweeks\fR, \fBmonths\fR, or \fByears\fR. (The singular forms are also
424 accepted.) The keyword \fBnext\fR is equivalent to an increment number of \fB+
425 1\fR. For example, the following are equivalent commands:
442 The format of the \fBat\fR command line shown here is guaranteed only for the
443 "C" locale. Other locales are not supported for \fBmidnight\fR, \fBnoon\fR,
444 \fBnow\fR, \fBmon\fR, \fBabmon\fR, \fBday\fR, \fBabday\fR, \fBtoday\fR,
445 \fBtomorrow\fR, \fBminutes\fR, \fBhours\fR, \fBdays\fR, \fBweeks\fR,
446 \fBmonths\fR, \fByears\fR, and \fBnext\fR.
449 Since the commands run in a separate shell invocation, running in a separate
450 process group with no controlling terminal, open file descriptors, traps and
451 priority inherited from the invoking environment are lost.
455 \fBExample 1 \fRTypical Sequence at a Terminal
458 This sequence can be used at a terminal:
463 $ at \(mim 0730 tomorrow
471 \fBExample 2 \fRRedirecting Output
474 This sequence, which demonstrates redirecting standard error to a pipe, is
475 useful in a command procedure (the sequence of output redirection
476 specifications is significant):
481 $ at now + 1 hour <<!
482 diff file1 file2 2>&1 >outfile | mailx mygroup
488 \fBExample 3 \fRSelf-rescheduling a Job
491 To have a job reschedule itself, \fBat\fR can be invoked from within the
492 at-job. For example, this "daily-processing" script named \fBmy.daily\fR runs
493 every day (although \fBcrontab\fR is a more appropriate vehicle for such work):
498 # my.daily runs every day
499 at now tomorrow < my.daily
506 \fBExample 4 \fRVarious Time and Operand Presentations
509 The spacing of the three portions of the "C" locale \fItimespec\fR is quite
510 flexible as long as there are no ambiguities. Examples of various times and
511 operand presentations include:
529 \fBExample 5 \fRTypical Sequence at a Terminal
532 This sequence can be used at a terminal:
545 \fBExample 6 \fRRedirecting Output
548 This sequence, which demonstrates redirecting standard error to a pipe, is
549 useful in a command procedure (the sequence of output redirection
550 specifications is significant):
556 diff file1 file2 2>&1 >outfile | mailx mygroup
562 .SH ENVIRONMENT VARIABLES
565 See \fBenviron\fR(5) for descriptions of the following environment variables
566 that affect the execution of \fBat\fR and \fBbatch\fR: \fBLANG\fR,
567 \fBLC_ALL\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBNLSPATH\fR, and
575 If the environment variable \fBDATEMSK\fR is set, \fBat\fR uses its value as
576 the full path name of a template file containing format strings. The strings
577 consist of format specifiers and text characters that are used to provide a
578 richer set of allowable date formats in different languages by appropriate
579 settings of the environment variable \fBLANG\fR or \fBLC_TIME\fR. The list of
580 allowable format specifiers is located in the \fBgetdate\fR(3C) manual page.
581 The formats described in the \fBOPERANDS\fR section for the \fItime\fR and
582 \fIdate\fR arguments, the special names \fBnoon\fR, \fBmidnight\fR, \fBnow\fR,
583 \fBnext\fR, \fBtoday\fR, \fBtomorrow\fR, and the \fIincrement\fR argument are
584 not recognized when \fBDATEMSK\fR is set.
593 Determine a name of a command interpreter to be used to invoke the at-job. If
594 the variable is unset or \fINULL\fR, \fBsh\fR is used. If it is set to a value
595 other than \fBsh\fR, the implementation uses that shell; a warning diagnostic
596 is printed telling which shell will be used.
605 Determine the timezone. The job is submitted for execution at the time
606 specified by \fItimespec\fR or \fB-t\fR \fItime\fR relative to the timezone
607 specified by the \fBTZ\fR variable. If \fItimespec\fR specifies a timezone, it
608 overrides \fBTZ\fR. If \fItimespec\fR does not specify a timezone and \fBTZ\fR
609 is unset or \fINULL\fR, an unspecified default timezone is used.
615 The following exit values are returned:
622 The \fBat\fR utility successfully submitted, removed or listed a job or jobs.
631 An error occurred, and the job will not be scheduled.
638 \fB\fB/usr/lib/cron/at.allow\fR \fR
641 names of users, one per line, who are authorized access to the \fBat\fR and
642 \fBbatch\fR utilities
648 \fB\fB/usr/lib/cron/at.deny\fR \fR
651 names of users, one per line, who are denied access to the \fBat\fR and
652 \fBbatch\fR utilities
658 See \fBattributes\fR(5) for descriptions of the following attributes:
667 ATTRIBUTE TYPE ATTRIBUTE VALUE
671 Interface Stability Standard
674 .SS "/usr/xpg4/bin/at"
682 ATTRIBUTE TYPE ATTRIBUTE VALUE
686 Interface Stability Standard
697 ATTRIBUTE TYPE ATTRIBUTE VALUE
701 Interface Stability Standard
704 .SS "/usr/xpg4/bin/batch"
712 ATTRIBUTE TYPE ATTRIBUTE VALUE
716 Interface Stability Standard
722 \fBauths\fR(1), \fBcrontab\fR(1), \fBcsh\fR(1), \fBdate\fR(1), \fBksh\fR(1),
723 \fBsh\fR(1), \fBtouch\fR(1), \fBulimit\fR(1), \fBumask\fR(1), \fBcron\fR(1M),
724 \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBshadow\fR(4), \fBqueuedefs\fR(4),
725 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)
729 Regardless of queue used, \fBcron\fR(1M) has a limit of 100 jobs in execution
733 There can be delays in \fBcron\fR at job execution. In some cases, these delays
734 can compound to the point that \fBcron\fR job processing appears to be hung.
735 All jobs are executed eventually. When the delays are excessive, the only
736 workaround is to kill and restart \fBcron\fR.