| blob | 570c979a097c48099a8ea503fa12d9a9fadc231e |
1 .\"
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/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
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.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
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.
30 .\"
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.
35 .\"
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]
41 .\"
42 .\" Copyright 1989 AT&T
43 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
44 .\" Portions Copyright (c) 2005, Sun Microsystems, Inc. All Rights Reserved
45 .\"
46 .TH AT 1 "Oct 25, 2017"
47 .SH NAME
48 at, batch \- execute commands at a later time
49 .SH SYNOPSIS
50 .LP
51 .nf
52 \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]
53 [\fB-q\fR \fIqueuename\fR] \fB-t\fR \fItime\fR
54 .fi
56 .LP
57 .nf
58 \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]
59 [\fB-q\fR \fIqueuename\fR] \fItimespec\fR...
60 .fi
62 .LP
63 .nf
64 \fB/usr/bin/at\fR \fB-l\fR [\fB-p\fR \fIproject\fR] [\fB-q\fR \fIqueuename\fR] [\fIat_job_id\fR \fI...\fR]
65 .fi
67 .LP
68 .nf
69 \fB/usr/bin/at\fR \fB-r\fR \fIat_job_id\fR \fI...\fR
70 .fi
72 .LP
73 .nf
74 \fB/usr/bin/batch\fR [\fB-p\fR \fIproject\fR]
75 .fi
77 .SH DESCRIPTION
78 .SS "at"
79 .sp
80 .LP
81 The \fBat\fR utility reads commands from standard input and groups them
82 together as an \fIat-job\fR, to be executed at a later time.
83 .sp
84 .LP
85 The at-job is executed in a separate invocation of the shell, running in a
86 separate process group with no controlling terminal, except that the
87 environment variables, current working directory, file creation mask (see
88 \fBumask\fR(1)), and system resource limits (for \fBsh\fR and \fBksh\fR only,
89 see \fBulimit\fR(1)) in effect when the \fBat\fR utility is executed is
90 retained and used when the at-job is executed.
91 .sp
92 .LP
93 When the at-job is submitted, the \fIat_job_id\fR and scheduled time are
94 written to standard error. The \fIat_job_id\fR is an identifier that is a
95 string consisting solely of alphanumeric characters and the period character.
96 The \fIat_job_id\fR is assigned by the system when the job is scheduled such
97 that it uniquely identifies a particular job.
98 .sp
99 .LP
100 User notification and the processing of the job's standard output and standard
101 error are described under the \fB-m\fR option.
102 .sp
103 .LP
104 Users are permitted to use \fBat\fR and \fBbatch\fR (see below) if their name
105 appears in the file \fB/usr/lib/cron/at.allow\fR. If that file does not exist,
106 the file \fB/usr/lib/cron/at.deny\fR is checked to determine if the user should
107 be denied access to \fBat\fR. If neither file exists, only a user with the
108 \fBsolaris.jobs.user\fR authorization is allowed to submit a job. If only
109 \fBat.deny\fR exists and is empty, global usage is permitted. The
110 \fBat.allow\fR and \fBat.deny\fR files consist of one user name per line.
111 .sp
112 .LP
113 \fBcron\fR and \fBat\fR jobs are not be executed if the user's account is
114 locked. Only accounts which are not locked as defined in \fBshadow\fR(4) will
115 have their job or process executed.
116 .SS "batch"
117 .sp
118 .LP
119 The \fBbatch\fR utility reads commands to be executed at a later time.
120 .sp
121 .LP
122 Commands of the forms:
123 .sp
124 .in +2
125 .nf
126 /usr/bin/batch [-p project]
127 .fi
128 .in -2
129 .sp
131 .sp
132 .LP
133 are respectively equivalent to:
134 .sp
135 .in +2
136 .nf
137 /usr/bin/at -q b -m [-p project] now
138 .fi
139 .in -2
140 .sp
142 .sp
143 .LP
144 where queue \fBb\fR is a special \fBat\fR queue, specifically for batch jobs.
145 Batch jobs are submitted to the batch queue for immediate execution. Execution
146 of submitted jobs can be delayed by limits on the number of jobs allowed to run
147 concurrently. See \fBqueuedefs\fR(4).
148 .SH OPTIONS
149 .sp
150 .LP
151 If the \fB-c\fR, \fB-k\fR, or \fB-s\fR options are not specified, the
152 \fBSHELL\fR environment variable by default determines which shell to use.
153 .sp
154 .LP
155 If \fBSHELL\fR is unset or \fBNULL\fR, \fB/usr/bin/sh\fR is used.
156 .sp
157 .LP
158 The following options are supported:
159 .sp
160 .ne 2
161 .na
162 \fB\fB-c\fR \fR
163 .ad
164 .RS 17n
165 C shell. \fBcsh\fR(1) is used to execute the at-job.
166 .RE
168 .sp
169 .ne 2
170 .na
171 \fB\fB-k\fR \fR
172 .ad
173 .RS 17n
174 Korn shell. \fBksh\fR(1) is used to execute the at-job.
175 .RE
177 .sp
178 .ne 2
179 .na
180 \fB\fB-s\fR \fR
181 .ad
182 .RS 17n
183 Bourne shell. \fBsh\fR(1) is used to execute the at-job.
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fB-f\fR \fIfile\fR \fR
190 .ad
191 .RS 17n
192 Specifies the path of a file to be used as the source of the at-job, instead of
193 standard input.
194 .RE
196 .sp
197 .ne 2
198 .na
199 \fB\fB-l\fR \fR
200 .ad
201 .RS 17n
202 (The letter ell.) Reports all jobs scheduled for the invoking user if no
203 \fIat_job_id\fR operands are specified. If \fIat_job_id\fRs are specified,
204 reports only information for these jobs.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fB-m\fR \fR
211 .ad
212 .RS 17n
213 Sends mail to the invoking user after the at-job has run, announcing its
214 completion. Standard output and standard error produced by the at-job are
215 mailed to the user as well, unless redirected elsewhere. Mail is sent even if
216 the job produces no output.
217 .sp
218 If \fB-m\fR is not used, the job's standard output and standard error is
219 provided to the user by means of mail, unless they are redirected elsewhere; if
220 there is no such output to provide, the user is not notified of the job's
221 completion.
222 .RE
224 .sp
225 .ne 2
226 .na
227 \fB\fB-p\fR \fIproject\fR\fR
228 .ad
229 .RS 17n
230 Specifies under which project the \fBat\fR or \fBbatch\fR job is run. When used
231 with the \fB-l\fR option, limits the search to that particular project. Values
232 for \fIproject\fR is interpreted first as a project name, and then as a
233 possible project \fBID\fR, if entirely numeric. By default, the user's current
234 project is used.
235 .RE
237 .sp
238 .ne 2
239 .na
240 \fB\fB-q\fR \fIqueuename\fR \fR
241 .ad
242 .RS 17n
243 Specifies in which queue to schedule a job for submission. When used with the
244 \fB-l\fR option, limits the search to that particular queue. Values for
245 \fIqueuename\fR are limited to the lower case letters \fBa\fR through \fBz\fR.
246 By default, at-jobs are scheduled in queue \fBa\fR. In contrast, queue \fBb\fR
247 is reserved for batch jobs. Since queue \fBc\fR is reserved for cron jobs, it
248 can not be used with the \fB-q\fR option.
249 .RE
251 .sp
252 .ne 2
253 .na
254 \fB\fB-r\fR \fIat_job_id\fR \fR
255 .ad
256 .RS 17n
257 Removes the jobs with the specified \fIat_job_id\fR operands that were
258 previously scheduled by the \fBat\fR utility.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fB-t\fR \fItime\fR \fR
265 .ad
266 .RS 17n
267 Submits the job to be run at the time specified by the \fItime\fR
268 option-argument, which must have the format as specified by the \fBtouch\fR(1)
269 utility.
270 .RE
272 .SH OPERANDS
273 .sp
274 .LP
275 The following operands are supported:
276 .sp
277 .ne 2
278 .na
279 \fB\fIat_job_id\fR \fR
280 .ad
281 .RS 14n
282 The name reported by a previous invocation of the \fBat\fR utility at the time
283 the job was scheduled.
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fItimespec\fR \fR
290 .ad
291 .RS 14n
292 Submit the job to be run at the date and time specified. All of the
293 \fItimespec\fR operands are interpreted as if they were separated by space
294 characters and concatenated. The date and time are interpreted as being in the
295 timezone of the user (as determined by the \fBTZ\fR variable), unless a
296 timezone name appears as part of \fItime\fR below.
297 .sp
298 In the "C" locale, the following describes the three parts of the time
299 specification string. All of the values from the \fBLC_TIME\fR categories in
300 the "C" locale are recognized in a case-insensitive manner.
301 .sp
302 .ne 2
303 .na
304 \fB\fItime\fR \fR
305 .ad
306 .RS 14n
307 The \fItime\fR can be specified as one, two or four digits. One- and two-digit
308 numbers are taken to be hours, four-digit numbers to be hours and minutes. The
309 time can alternatively be specified as two numbers separated by a colon,
310 meaning \fIhour\fR\fB:\fR\fIminute\fR. An AM/PM indication (one of the values
311 from the \fBam_pm\fR keywords in the \fBLC_TIME\fR locale category) can follow
312 the time; otherwise, a 24-hour clock time is understood. A timezone name of
313 \fBGMT\fR, \fBUCT\fR, or \fBZULU \fR(case insensitive) can follow to specify
314 that the time is in Coordinated Universal Time. Other timezones can be
315 specified using the \fBTZ\fR environment variable. The \fItime\fR field can
316 also be one of the following tokens in the "C" locale:
317 .sp
318 .ne 2
319 .na
320 \fB\fBmidnight\fR \fR
321 .ad
322 .RS 13n
323 Indicates the time 12:00 am (00:00).
324 .RE
326 .sp
327 .ne 2
328 .na
329 \fB\fBnoon\fR \fR
330 .ad
331 .RS 13n
332 Indicates the time 12:00 pm.
333 .RE
335 .sp
336 .ne 2
337 .na
338 \fB\fBnow\fR \fR
339 .ad
340 .RS 13n
341 Indicate the current day and time. Invoking \fBat\fR \fBnow\fR submits an
342 at-job for potentially immediate execution (that is, subject only to
343 unspecified scheduling delays).
344 .RE
346 .RE
348 .sp
349 .ne 2
350 .na
351 \fB\fIdate\fR \fR
352 .ad
353 .RS 14n
354 An optional \fIdate\fR can be specified as either a month name (one of the
355 values from the \fBmon\fR or \fBabmon\fR keywords in the \fBLC_TIME\fR locale
356 category) followed by a day number (and possibly year number preceded by a
357 comma) or a day of the week (one of the values from the \fBday\fR or
358 \fBabday\fR keywords in the \fBLC_TIME\fR locale category). Two special days
359 are recognized in the "C" locale:
360 .sp
361 .ne 2
362 .na
363 \fB\fBtoday\fR \fR
364 .ad
365 .RS 13n
366 Indicates the current day.
367 .RE
369 .sp
370 .ne 2
371 .na
372 \fB\fBtomorrow\fR \fR
373 .ad
374 .RS 13n
375 Indicates the day following the current day.
376 .RE
378 If no \fIdate\fR is given, \fBtoday\fR is assumed if the given time is greater
379 than the current time, and \fBtomorrow\fR is assumed if it is less. If the
380 given month is less than the current month (and no year is given), next year is
381 assumed.
382 .RE
384 .sp
385 .ne 2
386 .na
387 \fB\fIincrement\fR \fR
388 .ad
389 .RS 14n
390 The optional \fIincrement\fR is a number preceded by a plus sign (\fB+\fR) and
391 suffixed by one of the following: \fBminutes\fR, \fBhours\fR, \fBdays\fR,
392 \fBweeks\fR, \fBmonths\fR, or \fByears\fR. (The singular forms are also
393 accepted.) The keyword \fBnext\fR is equivalent to an increment number of \fB+
394 1\fR. For example, the following are equivalent commands:
395 .sp
396 .in +2
397 .nf
398 \fBat 2pm + 1 week
399 at 2pm next week\fR
400 .fi
401 .in -2
402 .sp
404 .RE
406 .RE
408 .SH USAGE
409 .sp
410 .LP
411 The format of the \fBat\fR command line shown here is guaranteed only for the
412 "C" locale. Other locales are not supported for \fBmidnight\fR, \fBnoon\fR,
413 \fBnow\fR, \fBmon\fR, \fBabmon\fR, \fBday\fR, \fBabday\fR, \fBtoday\fR,
414 \fBtomorrow\fR, \fBminutes\fR, \fBhours\fR, \fBdays\fR, \fBweeks\fR,
415 \fBmonths\fR, \fByears\fR, and \fBnext\fR.
416 .sp
417 .LP
418 Since the commands run in a separate shell invocation, running in a separate
419 process group with no controlling terminal, open file descriptors, traps and
420 priority inherited from the invoking environment are lost.
421 .SH EXAMPLES
422 .SS "at"
423 .LP
424 \fBExample 1 \fRTypical Sequence at a Terminal
425 .sp
426 .LP
427 This sequence can be used at a terminal:
429 .sp
430 .in +2
431 .nf
432 $ at \(mim 0730 tomorrow
433 sort < file >outfile
434 <EOT>
435 .fi
436 .in -2
437 .sp
439 .LP
440 \fBExample 2 \fRRedirecting Output
441 .sp
442 .LP
443 This sequence, which demonstrates redirecting standard error to a pipe, is
444 useful in a command procedure (the sequence of output redirection
445 specifications is significant):
447 .sp
448 .in +2
449 .nf
450 $ at now + 1 hour <<!
451 diff file1 file2 2>&1 >outfile | mailx mygroup
452 .fi
453 .in -2
454 .sp
456 .LP
457 \fBExample 3 \fRSelf-rescheduling a Job
458 .sp
459 .LP
460 To have a job reschedule itself, \fBat\fR can be invoked from within the
461 at-job. For example, this "daily-processing" script named \fBmy.daily\fR runs
462 every day (although \fBcrontab\fR is a more appropriate vehicle for such work):
464 .sp
465 .in +2
466 .nf
467 # my.daily runs every day
468 at now tomorrow < my.daily
469 daily-processing
470 .fi
471 .in -2
472 .sp
474 .LP
475 \fBExample 4 \fRVarious Time and Operand Presentations
476 .sp
477 .LP
478 The spacing of the three portions of the "C" locale \fItimespec\fR is quite
479 flexible as long as there are no ambiguities. Examples of various times and
480 operand presentations include:
482 .sp
483 .in +2
484 .nf
485 at 0815am Jan 24
486 at 8 :15amjan24
487 at now "+ 1day"
488 at 5 pm FRIday
489 at '17
490 utc+
491 30minutes'
492 .fi
493 .in -2
494 .sp
496 .SS "batch"
497 .LP
498 \fBExample 5 \fRTypical Sequence at a Terminal
499 .sp
500 .LP
501 This sequence can be used at a terminal:
503 .sp
504 .in +2
505 .nf
506 $ batch
507 sort <file >outfile
508 <EOT>
509 .fi
510 .in -2
511 .sp
513 .LP
514 \fBExample 6 \fRRedirecting Output
515 .sp
516 .LP
517 This sequence, which demonstrates redirecting standard error to a pipe, is
518 useful in a command procedure (the sequence of output redirection
519 specifications is significant):
521 .sp
522 .in +2
523 .nf
524 $ batch <<!
525 diff file1 file2 2>&1 >outfile | mailx mygroup
526 !
527 .fi
528 .in -2
529 .sp
531 .SH ENVIRONMENT VARIABLES
532 .sp
533 .LP
534 See \fBenviron\fR(5) for descriptions of the following environment variables
535 that affect the execution of \fBat\fR and \fBbatch\fR: \fBLANG\fR,
536 \fBLC_ALL\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBNLSPATH\fR, and
537 \fBLC_TIME\fR.
538 .sp
539 .ne 2
540 .na
541 \fB\fBDATEMSK\fR \fR
542 .ad
543 .RS 12n
544 If the environment variable \fBDATEMSK\fR is set, \fBat\fR uses its value as
545 the full path name of a template file containing format strings. The strings
546 consist of format specifiers and text characters that are used to provide a
547 richer set of allowable date formats in different languages by appropriate
548 settings of the environment variable \fBLANG\fR or \fBLC_TIME\fR. The list of
549 allowable format specifiers is located in the \fBgetdate\fR(3C) manual page.
550 The formats described in the \fBOPERANDS\fR section for the \fItime\fR and
551 \fIdate\fR arguments, the special names \fBnoon\fR, \fBmidnight\fR, \fBnow\fR,
552 \fBnext\fR, \fBtoday\fR, \fBtomorrow\fR, and the \fIincrement\fR argument are
553 not recognized when \fBDATEMSK\fR is set.
554 .RE
556 .sp
557 .ne 2
558 .na
559 \fB\fBSHELL\fR \fR
560 .ad
561 .RS 12n
562 Determine a name of a command interpreter to be used to invoke the at-job. If
563 the variable is unset or \fINULL\fR, \fBsh\fR is used. If it is set to a value
564 other than \fBsh\fR, the implementation uses that shell; a warning diagnostic
565 is printed telling which shell will be used.
566 .RE
568 .sp
569 .ne 2
570 .na
571 \fB\fBTZ\fR \fR
572 .ad
573 .RS 12n
574 Determine the timezone. The job is submitted for execution at the time
575 specified by \fItimespec\fR or \fB-t\fR \fItime\fR relative to the timezone
576 specified by the \fBTZ\fR variable. If \fItimespec\fR specifies a timezone, it
577 overrides \fBTZ\fR. If \fItimespec\fR does not specify a timezone and \fBTZ\fR
578 is unset or \fINULL\fR, an unspecified default timezone is used.
579 .RE
581 .SH EXIT STATUS
582 .sp
583 .LP
584 The following exit values are returned:
585 .sp
586 .ne 2
587 .na
588 \fB\fB0\fR \fR
589 .ad
590 .RS 7n
591 The \fBat\fR utility successfully submitted, removed or listed a job or jobs.
592 .RE
594 .sp
595 .ne 2
596 .na
597 \fB\fB>0\fR \fR
598 .ad
599 .RS 7n
600 An error occurred, and the job will not be scheduled.
601 .RE
603 .SH FILES
604 .sp
605 .ne 2
606 .na
607 \fB\fB/usr/lib/cron/at.allow\fR \fR
608 .ad
609 .RS 27n
610 names of users, one per line, who are authorized access to the \fBat\fR and
611 \fBbatch\fR utilities
612 .RE
614 .sp
615 .ne 2
616 .na
617 \fB\fB/usr/lib/cron/at.deny\fR \fR
618 .ad
619 .RS 27n
620 names of users, one per line, who are denied access to the \fBat\fR and
621 \fBbatch\fR utilities
622 .RE
624 .SH ATTRIBUTES
625 .sp
626 .LP
627 See \fBattributes\fR(5) for descriptions of the following attributes:
628 .SS "/usr/bin/at"
629 .sp
631 .sp
632 .TS
633 box;
634 c | c
635 l | l .
636 ATTRIBUTE TYPE ATTRIBUTE VALUE
637 _
638 CSI Not enabled
639 _
640 Interface Stability Standard
641 .TE
643 .SS "/usr/bin/batch"
644 .sp
646 .sp
647 .TS
648 box;
649 c | c
650 l | l .
651 ATTRIBUTE TYPE ATTRIBUTE VALUE
652 _
653 CSI Enabled
654 _
655 Interface Stability Standard
656 .TE
658 .SH SEE ALSO
659 .sp
660 .LP
661 \fBauths\fR(1), \fBcrontab\fR(1), \fBcsh\fR(1), \fBdate\fR(1), \fBksh\fR(1),
662 \fBsh\fR(1), \fBtouch\fR(1), \fBulimit\fR(1), \fBumask\fR(1), \fBcron\fR(8),
663 \fBgetdate\fR(3C), \fBauth_attr\fR(4), \fBshadow\fR(4), \fBqueuedefs\fR(4),
664 \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)
665 .SH NOTES
666 .sp
667 .LP
668 Regardless of queue used, \fBcron\fR(8) has a limit of 100 jobs in execution
669 at any time.
670 .sp
671 .LP
672 There can be delays in \fBcron\fR at job execution. In some cases, these delays
673 can compound to the point that \fBcron\fR job processing appears to be hung.
674 All jobs are executed eventually. When the delays are excessive, the only
675 workaround is to kill and restart \fBcron\fR.