-.\"
-.\" Copyright (c) 1993 Christopher G. Demetriou
-.\" All rights reserved.
-.\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\" notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\" notice, this list of conditions and the following disclaimer in the
-.\" documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\" must display the following acknowledgement:
-.\" This product includes software developed by Christopher G. Demetriou.
-.\" 3. The name of the author may not be used to endorse or promote products
-.\" derived from this software without specific prior written permission
-.\"
-.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
-.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
-.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
-.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
-.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
-.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
-.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-.\"
-.\" $Id: at.1,v 1.1.1.1 1999/05/02 04:21:18 wsanchez Exp $
-.\"
-.Dd December 5, 1993
+.\" $FreeBSD: src/usr.bin/at/at.man,v 1.34 2003/03/26 02:38:18 keramida Exp $
+.Dd January 13, 2002
.Dt "AT" 1
-.Os NetBSD 0.9a
+.Os
.Sh NAME
-.Nm at, batch, atq, atrm
+.Nm at ,
+.Nm batch ,
+.Nm atq ,
+.Nm atrm
.Nd queue, examine, or delete jobs for later execution
-.\"
-.Sh SYOPSIS
+.Sh SYNOPSIS
.Nm at
.Op Fl q Ar queue
.Op Fl f Ar file
-.Op Fl m
+.Op Fl mldbv
.Ar time
+.Nm at
+.Op Fl q Ar queue
+.Op Fl f Ar file
+.Op Fl mldbv
+.Fl t
+.Sm off
+.Op Oo Ar CC Oc Ar YY
+.Ar MM DD hh mm Op . Ar SS
+.Sm on
+.Nm at
+.Fl c Ar job Op Ar job ...
+.Nm at
+.Fl l Op Ar job ...
+.Nm at
+.Fl l
+.Fl q Ar queue
+.Nm at
+.Fl r Ar job Op Ar job ...
.Pp
.Nm atq
.Op Fl q Ar queue
.Op Ar job ...
.Pp
.Nm batch
+.Op Fl q Ar queue
.Op Fl f Ar file
-.Op Fl m
-.Ar time
+.Op Fl mv
+.Op Ar time
.Sh DESCRIPTION
The
.Nm at
and
.Nm batch
-utilities read commands from the standard input or a specified file
-which are to be executed at a later time, using
+utilities
+read commands from standard input or a specified file.
+The commands are executed at a later time, using
.Xr sh 1 .
-.Pp
-The functions of the commands are as follows:
.Bl -tag -width indent
.It Nm at
-Executes commands at a specified time.
+executes commands at a specified time;
.It Nm atq
-Lists the user's pending jobs, unless the user is
-the superuser. In that case, everybody's jobs are
-listed.
+lists the user's pending jobs, unless the user is the superuser; in that
+case, everybody's jobs are listed;
.It Nm atrm
-Deletes jobs.
+deletes jobs;
.It Nm batch
-executes commands when system load levels permit.
-In other words, it executes the commands when the load
-average drops below a specified level.
+executes commands when system load levels permit; in other words, when the load average
+drops below _LOADAVG_MX (1.5), or the value specified in the invocation of
+.Nm atrun .
.El
.Pp
+The
+.Nm at
+utility allows some moderately complex
+.Ar time
+specifications.
+It accepts times of the form
+.Ar HHMM
+or
+.Ar HH:MM
+to run a job at a specific time of day.
+(If that time is already past, the next day is assumed.)
+As an alternative, the following keywords may be specified:
+.Em midnight ,
+.Em noon ,
+or
+.Em teatime
+(4pm)
+and time-of-day may be suffixed with
+.Em AM
+or
+.Em PM
+for running in the morning or the evening.
+The day on which the job is to be run may also be specified
+by giving a date in the form
+.Ar \%month-name day
+with an optional
+.Ar year ,
+or giving a date of the forms
+.Ar DD.MM.YYYY ,
+.Ar DD.MM.YY ,
+.Ar MM/DD/YYYY ,
+.Ar MM/DD/YY ,
+.Ar MMDDYYYY , or
+.Ar MMDDYY .
+The specification of a date must follow the specification of
+the time of day.
+Time can also be specified as:
+.Op Em now
+.Em + Ar count \%time-units ,
+where the time-units can be
+.Em minutes ,
+.Em hours ,
+.Em days ,
+.Em weeks ,
+.Em months
+or
+.Em years
+and
+.Nm at
+may be told to run the job today by suffixing the time with
+.Em today
+and to run the job tomorrow by suffixing the time with
+.Em tomorrow .
+The shortcut
+.Em next
+can be used instead of
+.Em + 1 .
+.Pp
+For example, to run a job at 4pm three days from now, use
+.Nm at Ar 4pm + 3 days ,
+to run a job at 10:00am on July 31, use
+.Nm at Ar 10am Jul 31
+and to run a job at 1am tomorrow, use
+.Nm at Ar 1am tomorrow .
+.Pp
+The
+.Nm at
+utility also supports the
+.Tn POSIX
+time format (see
+.Fl t
+option).
+.Pp
For both
.Nm at
and
.Nm batch ,
-the working directory, environment (except for the variables
-.Nm TERM ,
-.Nm TERMCAP ,
-.Nm DISPLAY ,
+commands are read from standard input or the file specified
+with the
+.Fl f
+option.
+The working directory, the environment (except for the variables
+.Ev TERM ,
+.Ev TERMCAP ,
+.Ev DISPLAY
and
-.Nm _ )
-and the umask are retained from the time of invocation. The user
-will be mailed the standard output and standard error from
-his commands if any output is generated. If
+.Em _ ) ,
+and the
+.Ar umask
+are retained from the time of invocation.
+An
+.Nm at
+or
+.Nm batch
+command invoked from a
+.Xr su 1
+shell will retain the current userid.
+The user will be mailed standard error and standard output from his
+commands, if any.
+Mail will be sent using the command
+.Xr sendmail 8 .
+If
.Nm at
is executed from a
.Xr su 1
shell, the owner of the login shell will receive the mail.
+.Pp
+The superuser may use these commands in any case.
+For other users, permission to use
+.Nm at
+is determined by the files
+.Pa _PERM_PATH/at.allow
+and
+.Pa _PERM_PATH/at.deny .
+.Pp
+If the file
+.Pa _PERM_PATH/at.allow
+exists, only usernames mentioned in it are allowed to use
+.Nm at .
+In these two files,
+a user is considered to be listed
+only if the user name has no blank or other characters
+before it on its line and a newline character immediately after the name,
+even at the end of the file.
+Other lines are ignored and may be used for comments.
+.Pp
+If
+.Pa _PERM_PATH/at.allow
+does not exist,
+.Pa _PERM_PATH/at.deny
+is checked, every username not mentioned in it is then allowed
+to use
+.Nm at .
+.Pp
+If neither exists, only the superuser is allowed use of
+.Nm at .
+.Sh IMPLEMENTATION NOTES
+Note that
+.Nm at
+is implemented through the
+.Xr launchd 8
+daemon periodically invoking
+.Xr atrun 8 ,
+which is disabled by default.
+See
+.Xr atrun 8
+for information about enabling
+.Nm atrun .
.Sh OPTIONS
.Bl -tag -width indent
-The available options are as follows:
+.It Fl b
+Is an alias for
+.Nm batch .
+.It Fl c
+Cat the jobs listed on the command line to standard output.
+.It Fl d
+Is an alias for
+.Nm atrm
+(this option is deprecated; use
+.Fl r
+instead).
+.It Fl f Ar file
+Read the job from
+.Ar file
+rather than standard input.
+.It Fl l
+With no arguments, list all jobs for the invoking user.
+If one or more
+job numbers are given, list only those jobs.
+.It Fl m
+Send mail to the user when the job has completed even if there was no
+output.
.It Fl q Ar queue
-Use the specified queue. A queue designation consists
-of a single letter; valid queue designation range from
+Use the specified queue.
+A queue designation consists of a single letter; valid queue designations
+range from
.Ar a
to
-.Ar l .
+.Ar z
+and
+.Ar A
+to
+.Ar Z .
The
-.Ar a
-queue is the default, and
-.Ar b
-is the batch queue. Queues with higher letters run with
-increased niceness. If
+.Ar _DEFAULT_AT_QUEUE
+queue (a) is the default for
+.Nm at
+and the
+.Ar _DEFAULT_BATCH_QUEUE
+queue (b) is the default for
+.Nm batch .
+Queues with higher letters run with increased niceness.
+If a job is submitted to a queue designated with an uppercase letter, it
+is treated as if it had been submitted to batch at that time.
+If
.Nm atq
-is given a specific queue, it will only show jobs pending
-in that queue.
-.It Fl m
-Send mail to the user when the job has completed, even if
-there was no output.
-.It Fl f Ar file
-Reads the job from
-.Ar file
-rather than the standard input.
-.It Fl v
-Shows completed but not yet deleted jobs in the queue.
-.Sh TIME SPECIFICATION
-.Nm At
-allows some moderately complex time specifications.
-It accepts times of the form
-.Ar HHMM
-or
-.Ar HH:MM
-to run a job at a specific time of day. If
-that time is already passed, the next day is assumed.
-You may also specify
-.Nm midnight ,
-.Nm noon ,
-or
-.Nm teatime
-(4PM) and you can give a time of day suffixed with
-.Nm AM
-or
-.Nm PM
-for running in the morning or the evening. You can
-also specify the date on which the job will be run
-by giving a date in the form
-.Ar month-name day
-with an optional
-.Ar year ,
-or giving a date of the form
-.Ar MMDDYY ,
-.Ar MM/DD/YY
-or
-.Ar DD.MM.YY .
-You can also give times like
-.Nm now +
-.Ar count time-units ,
-where the time units can be
-.Nm minutes, hours, days,
-or
-.Nm weeks
-You can suffix the time with
-.Nm today
-to run the job today, or
-.Nm tomorrow
-to run the job tomorrow.
+is given a specific queue, it will only show jobs pending in that queue.
+.It Fl r
+Remove the specified jobs.
+.It Fl t
+Specify the job time using the \*[Px] time format.
+The argument should be in the form
+.Sm off
+.Op Oo Ar CC Oc Ar YY
+.Ar MM DD hh mm Op . Ar SS
+.Sm on
+where each pair of letters represents the following:
.Pp
-For example, to run a job at 4PM three days from now, you
-would specify a time of
-.Nm 4PM + 3 days .
-To run a job at 10:00AM on on July 31, you would specify
-a time of
-.Nm 10AM Jul 31 .
-Finally, to run a job at 1AM tomorrow, you would specify
-a time of
-.Nm 1AM tomorrow .
+.Bl -tag -width indent -compact -offset indent
+.It Ar CC
+The first two digits of the year (the century).
+.It Ar YY
+The second two digits of the year.
+.It Ar MM
+The month of the year, from 1 to 12.
+.It Ar DD
+the day of the month, from 1 to 31.
+.It Ar hh
+The hour of the day, from 0 to 23.
+.It Ar mm
+The minute of the hour, from 0 to 59.
+.It Ar SS
+The second of the minute, from 0 to 61.
+.El
+.Pp
+If the
+.Ar CC
+and
+.Ar YY
+letter pairs are not specified, the values default to the current
+year.
+If the
+.Ar SS
+letter pair is not specified, the value defaults to 0.
+.It Fl v
+For
+.Nm atq ,
+shows completed but not yet deleted jobs in the queue; otherwise
+shows the time the job will be executed.
+.El
.Sh FILES
-.Bl -tag -width /var/at/lockfile -compact
-.It Pa /var/at/jobs
-Directory containing job files
-.It Pa /var/at/spool
-Directory containing output spool files
-.It Pa /var/at/lockfile
-Job-creation lock file.
-.It Pa /var/run/utmp
+.Bl -tag -width _ATJOB_DIR/_LOCKFILE -compact
+.It Pa _ATJOB_DIR
+directory containing job files
+(/usr/lib/cron/jobs/)
+.It Pa _ATJOB_DIR/_LOCKFILE
+job-creation lock file
+(/usr/lib/cron/jobs/...)
+.It Pa _ATSPOOL_DIR
+directory containing output spool files
+(/usr/lib/cron/spool/)
+.It Pa _PERM_PATH/at.allow
+allow permission control
+(/usr/lib/cron/at.allow)
+.It Pa _PERM_PATH/at.deny
+deny permission control
+(/usr/lib/cron/at.deny)
+.It Pa /var/run/utmpx
+login records
.El
.Sh SEE ALSO
-.Xr crond 8 ,
.Xr nice 1 ,
.Xr sh 1 ,
-.Xr atrun 8
-.Sh AUTHOR
-.Bl -tag
-Thomas Koenig, ig25@rz.uni-karlsruhe.de
-.El
+.Xr umask 2 ,
+.Xr compat 5 ,
+.Xr atrun 8 ,
+.Xr cron 8 ,
+.Xr sendmail 8
.Sh BUGS
-Traditional access control to
+If the file
+.Pa /var/run/utmpx
+is not available or corrupted,
+or if the user is not logged on at the time
+.Nm at
+is invoked, the mail is sent to the userid found
+in the environment variable
+.Ev LOGNAME .
+If that is undefined or empty, the current userid is assumed.
+.Pp
+The
.Nm at
and
.Nm batch
-via the files
-.Pa /var/at/at.allow
-and
-.Pa /var/at/at.deny
-is not implemented.
+utilities
+as presently implemented are not suitable when users are competing for
+resources.
+If this is the case, another batch system such as
+.Em nqs
+may be more suitable.
.Pp
-If the file
-.Pa /var/run/utmp
-is not available or corrupted, or if the user is not
-logged in at the time
-.Nm at
-is invoked, the mail is sent to the userid found in the
-environment variable
-.Nm LOGNAME .
-If that is undefined or empty, the current userid is assumed.
+Specifying a date past 2038 may not work on some systems.
+.Sh AUTHORS
+At was mostly written by
+.An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de .
+The time parsing routines are by
+.An David Parsons Aq orc@pell.chi.il.us ,
+with minor enhancements by
+.An Joe Halpin Aq joe.halpin@attbi.com .
projects / apple / system_cmds.git / blobdiff