at - Run a command at a specified time

Format

at [-m] [-f file] [-q queue] -t time
at [-m] [-f file] [-q queue] timespec
at -r [-q queue] at_job...
at -l [-q queue] [at_job...]

Description

at lets you set up a series of commands to be run later. It reads the commands from the standard input (stdin) or from a file specified with the -f option. When the commands run, they have the same environment variables, working directory, file creation mask, and so on that are set up when you run the at command; however, at does not typically preserve open file descriptors, traps, or priority inherited from the working environment.

Typically, you redirect the standard output (stdout) from these commands to files so you can read the files after the system runs the commands. at mails the standard output (stdout) and standard error output (stderr) to you if you do not redirect them.

The at command displays an at_job identifier when you submit commands, along with the time that the system is to run the commands.

at, batch, and crontab submit jobs to cron; the data in these jobs may contain double-byte characters. When the jobs are run, the data in the jobs are interpreted in the locale that cron is using. Since it is strongly recommended that cron be started in the POSIX locale, double-byte characters in the job may not be interpreted correctly. You can get around this by calling setlocale() in the job itself.

Options

-f file: Reads commands from file rather than from standard input (stdin).
-l: Reports on standard output (stdout) all jobs you have scheduled and when the system is to run them if you do not specify at_job. Specifying at_job reports information about those jobs only.
-m: Sends you mail after your job has finished running. If you did not redirect the stdout and stderr, at also mails these to you. If stdout or stderr is non-null, at mails this output to you even if you do not specify -m.
-q queue: Specifies the queue your at job is to be recorded in or removed from. queue can be any single-byte character except a space, a tab, a null character, or a number sign (#). By default, at stores all its jobs in a queue called a, and batch stores all its jobs in a queue called b. If used with this option, -l only reports information about at jobs in queue.
-r at_job: Removes previously scheduled at jobs. The at_job arguments must be the identifiers assigned to the jobs when you set them up with at.
-t time: Specifies the time for the system to run the job. Specify time in the same format as the time argument for touch.

When you do not use the -t option, you can use a timespec argument to specify the time. A timespec argument consists of three parts: a time, a date, and an increment (in that order). You must always specify the time, but you can omit the date, the increment, or both. Following are possible time formats:

Format: Meaning
hhmm: hh hours, mm minutes, 24-hour clock
hh:mm: hh hours, mm minutes, 24-hour clock
h:mm: h hours, mm minutes, 24-hour clock
h:m: h hours, m minutes, 24-hour clock
hh:mm zone: zone is time zone
hh:mmam: Morning, 12-hour clock
hh:mmam zone: Morning, 12-hour clock in given time zone
hh:mmpm: Afternoon, 12-hour clock
hh:mmpm zone: Afternoon, 12-hour clock in given time zone
noon: Noon
midnight: Midnight
varnextvar: The current time, next day that meets date and increment
varnowvar: The current time today

All minute specifications are optional. For example, to specify an at job to run at 1:00 p.m., you can enter

at 1pm

The z/OS shell only supports the time zones GMT, CUT, UTC, and ZULU, all of which stand for Coordinated Universal Time (often called Greenwich Mean Time). If you do not specify a zone, at interprets times with respect to the TZ environment variable.

TZ environment variable explains how to set the local time zone with the TZ environment variable.

Possible date formats are shown in the following list:

Format: Meaning
month day: month is the full name, or the three-letter abbreviation (as in January or Jan)
month day, year: day and year given as appropriate numbers
weekday: weekday is the full name or the three-letter abbreviation (as in Monday or Mon)
vartodayvar: The current day
vartomorrowvar: Next day

The increment is added to the time and date you specify with the preceding parts of timespec. It has the format + n units where n is a number and units is one of the following:

minute     minutes    hour     hours
day        days       week     weeks
month      months     year     years

Here are some sample time specifications:

0655
1855
18:55
6:55pm
6:55 pm Jan 10
now + 3 hours
noon tomorrow
midnight Friday

Environment variables

at uses the following environment variables:

SHELL: Contains the name of the shell used to invoke the at job.
TZ: Specifies the default time zone for all times given on the command line. If you include a time zone as part of time or timespec, it overrides the value of TZ. TZ environment variable explains how to set the local time zone with the TZ environment variable.

Usage notes

at jobs that contain a line consisting of just the string "!!!ATEOF!!!" fail with unexpected results.

Localization

at uses the following localization variables:

LANG
LC_ALL
LC_CTYPE
LC_MESSAGES
LC_TIME
NLSPATH

The keywords midnight, noon, today, and tomorrow are valid only in the POSIX locale.

Exit values

0: Successful completion.
>0: Returned if the command fails for any reason.

If an error occurs, at does not schedule, remove, or list the job.

Portability

POSIX.2 User Portability Extension, UNIX systems.

Related information

batch, bg, cron, crontab, touch, tcsh