at(1)

at, batch -- execute commands at a later time

Synopsis

at [-f script] [-m] [-q queuename] -t time

at [-f script] [-m] [-q queuename] timespec [date] [+ increment]

at -d job

at -l -q queuename

at -l [job ...]

at -r job ...

a t -z job

at -Z job

batch

Description

at and batch read commands from standard input to be executed at a later time.

at allows you to specify when the commands should be executed; date and time are recognized according to the locale specified in the LC_TIME environment variable (see LANG on environ(5)), as described below.

Jobs queued with batch will execute when system load level permits. The batch command is equivalent to the command:

   at -q b -m now

Options

The at command may be used with the following options:

-d job

Displays the contents of the specified job.

-f script

Reads commands to be executed from the named script file.

-l [job]

Reports all jobs scheduled for the invoking user, or just the jobs specified. An unprivileged user is restricted to displaying information only on jobs that the user owns and that are at the user's level. A user with the appropriate privileges is able to display information about all jobs.

-m

Sends mail to the user after the job has been completed. Mail is sent even if the job does not produce output. Standard output and standard error output are mailed to the user unless redirected elsewhere. -m has no effect on jobs which already print to standard output or standard error; the mail message will not be duplicated. The environment variables, current directory, umask, and ulimit are retained when the commands are executed. Open file descriptors, traps, and priority are lost.

-q queuename

Specify in which queue to schedule a job for submission. The queuename can be a or b. When used with the -l option, limit the search to that particular queue. By default, at jobs will be scheduled in queue a; queue b is reserved for batch jobs.

-r job

Removes specified jobs previously scheduled with at for the invoking user. An unprivileged user is restricted to remove only jobs that the user owns. A user with the appropriate privileges is able to remove any job.

-t time

Submit a job to be run at the time specified by the time option-argument; which has the same format as the time option argument on the touch(1) manual page. An execution time can also be specified with the timespec argument; see the section ``The timespec Argument''. The time argument is a decimal number of the form:

   	[[CC]YY]MMDDhhmm[.SS]

where each two digits represent the following:

MM month of the year (01-12)

DD day of the month (01-31)

hh hour of the day (00-23)

mm minute of the hour (00-59)

CC first two digits of the year (the century)

YY second two digits of the year

SS second of the minute (00-61)

CC and YY are optional. If neither is given, the current year is assumed. If YY is specified, but CC is not, CC is derived as follows:

If YY is: CC becomes:

69-99 19

00-68 20

The range for SS is (00-61), because of leap seconds. If SS is 60 or 61 and the resulting time, as affected by the TZ environment variable, does not refer to a leap second; the resulting time shall be one or two seconds after a time where SS is 59. If SS is not given it is assumed to be zero.

The invoking user's login shell in the /etc/passwd file is used to execute jobs, provided the shell specified ends in "/sh"; otherwise, /usr/bin/sh is used.

Standard output and standard error output are mailed to the user unless they are redirected elsewhere. The shell environment variables, current directory, umask, and ulimit are retained when the commands are executed. Open file descriptors, traps, and priority are lost.

Users are permitted to use at if their name appears in the file /etc/cron.d/at.allow. If that file does not exist, the file /etc/cron.d/at.deny is checked to determine if the user should be denied access to at. If neither file exists, only root is allowed to submit a job. If only at.deny exists and is empty, global usage is permitted. The allow/deny files consist of one user name per line. These files can only be modified by a privileged user.

Environment variables

If the POSIX2 environment variable is set, then standard error output appears as follows:

   Job jobid at date

If the POSIX2 environment variable is set, then no WARNING message is displayed when a job may not be executed at the proper time.

If the environment variable DATEMSK is set, at will use its value as the full path name of a template file containing format strings. The strings consist of field descriptors and text characters and are used to provide a richer set of allowable date formats in different languages by appropriate settings of the environment variable LC_TIME (see LANG on environ(5)). (See getdate(3C) for the allowable list of field descriptors; this list is a subset of the descriptors allowed by calendar(1) that are listed on the date(1) manual page.) The formats described for the time and date arguments, the special names noon, midnight, now, next, today, tomorrow, and the increment argument are not recognized when DATEMSK is set.

The timespec argument

A timespec argument can be used (without a -t option) to specify a time as follows, where h is hours and m is minutes:

   h,
   hh,
   hhmm,
   h: m,
   h: mm,
   hh: m,
   hh: mm.

A 24-hour clock is assumed, unless am or pm is appended to timespec. If zulu is appended to timespec, it means Greenwich Mean Time (GMT). timespec can also take on the values: noon, midnight, and now.

An optional date may be specified as either a month name followed by a day number (and possibly a year number preceded by a comma) or a day of the week. Month and weekday names used for date are recognized according to the locale specified in the LC_TIME environment variable (see LANG on environ(5)). Both the month name and the day of the week may be spelled out or abbreviated to three characters. Two special ``days,'' today and tomorrow, are recognized. If no date is given, today is assumed if the given hour is greater than the current hour and tomorrow is assumed if it is less. If the given month is less than the current month (and no year is given), next year is assumed.

The optional increment is simply a number suffixed by one of the following: minutes, hours, days, weeks, months, or years. (The singular form is also accepted.) Note that when increment is 1 minute, at displays the warning

   job may not be executed at the proper time

because the cron(1M) command's smallest unit is the minute; that is, an at job entered at 12:01:45 and requested to run in one minute will run at 12:02:00 rather than 12:02:45. The modifier next may precede the increment; it means ``+ 1.''

Thus valid commands include:

   at 0815am Jan 24
   at 8:15am Jan 24
   at now + 1 day
   at now next day
   at 5 pm Friday

Output

When scheduling a job, at and batch write the job number and schedule time to standard error in this format:

   UX:at: INFO: Job jobid at date

If POSIX2 is set, then the "UX:at: INFO:" normally prepended to this message is omitted.

You can also get job numbers by typing at -l.

Examples

The at and batch commands read from standard input the commands to be executed at a later time. sh(1) provides different ways of specifying standard input. Within your commands, it may be useful to redirect standard output.

This sequence can be used at a terminal:

batch
sort filename > outfile
<Ctrl>-d (hold down ``control'' and press ``d'')

This sequence, which shows redirecting standard error to a pipe, is useful in a shell procedure (the sequence of output redirection specifications is significant):

   batch <<!
   sort filename 2>&1 > outfile | mail loginid
   !

To have a job reschedule itself, invoke at from within the shell procedure, by including code similar to the following within the shell file:

   echo "sh shellfile" | at 1900 thursday next week

The following example shows the possible contents of a template file AT.TEMPL in /var/tmp.

   %I %p, the %est of %B of the year %Y run the following job
   %I %p, the %end of %B of the year %Y run the following job
   %I %p, the %erd of %B of the year %Y run the following job
   %I %p, the %eth of %B of the year %Y run the following job
   %d/%m/%y
   %H:%M:%S
   %I:%M%p

The following are examples of valid invocations if the environment variable DATEMSK is set to /var/tmp/AT.TEMPL.

   at 2 PM, the 3rd of July of the year 2000 run the following job
   at 3/4/99
   at 10:30:30
   at 2:30PM

Files

/etc/cron.d: main cron directory
/etc/cron.d/at.allow: list of allowed users
/etc/cron.d/at.deny: list of denied users
/etc/cron.d/queuedefs: scheduling information
/var/spool/cron/atjobs: spool area
/usr/lib/locale/locale/LC_MESSAGES/uxcore: language-specific message file (See LANG on environ(5).)

References

atq(1), atrm(1), calendar(1), cron(1M), crontab(1), date(1), environ(5), getdate(3C), kill(1), mail(1), nice(1), ps(1), sh(1), sort(1).

MM	month of the year (01-12)
DD	day of the month (01-31)
hh	hour of the day (00-23)
mm	minute of the hour (00-59)
CC	first two digits of the year (the century)
YY	second two digits of the year
SS	second of the minute (00-61)