394 lines
8.5 KiB
Groff
394 lines
8.5 KiB
Groff
.\" $OpenBSD: at.1,v 1.56 2022/10/22 06:41:04 jmc Exp $
|
|
.\"
|
|
.\" Copyright (C) 1993, 1994 Thomas Koenig
|
|
.\" Copyright (C) 1993 David Parsons
|
|
.\" Copyright (C) 2002 Todd C. Miller
|
|
.\"
|
|
.\" 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. The name of the author(s) 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(S) ``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(S) 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.
|
|
.\"
|
|
.Dd $Mdocdate: October 22 2022 $
|
|
.Dt AT 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm at ,
|
|
.Nm batch
|
|
.Nd queue, examine or delete jobs for later execution
|
|
.Sh SYNOPSIS
|
|
.Nm at
|
|
.Op Fl bm
|
|
.Op Fl f Ar file
|
|
.Op Fl l Op Ar job ...
|
|
.Op Fl q Ar queue
|
|
.Fl t Ar time_arg | timespec
|
|
.Nm at
|
|
.Fl c | r
|
|
.Ar job ...
|
|
.Nm batch
|
|
.Op Fl m
|
|
.Op Fl f Ar file
|
|
.Op Fl q Ar queue
|
|
.Op Ar timespec
|
|
.Sh DESCRIPTION
|
|
.Nm at
|
|
and
|
|
.Nm batch
|
|
read commands from standard input or a specified file which
|
|
are to be executed at a later time, via the user's shell as
|
|
specified by the
|
|
.Ev SHELL
|
|
environment variable.
|
|
If
|
|
.Ev SHELL
|
|
is not set, the shell in the user's password database entry is used
|
|
instead.
|
|
If all else fails,
|
|
.Xr sh 1
|
|
will be used.
|
|
.Pp
|
|
The related programs are as follows:
|
|
.Bl -tag -width Ds
|
|
.It Nm at
|
|
Executes commands at a specified time.
|
|
.It Nm batch
|
|
Executes commands when system load levels permit.
|
|
In other words, when
|
|
the load average drops below 1.5, or the value specified in the invocation of
|
|
.Xr cron 8 .
|
|
.El
|
|
.Pp
|
|
The options are as follows:
|
|
.Bl -tag -width indent
|
|
.It Fl b
|
|
An alias for
|
|
.Nm batch .
|
|
.It Fl c Ar job ...
|
|
Prints the jobs listed on the command line to standard output.
|
|
.It Fl f Ar file
|
|
Reads the job from
|
|
.Ar file
|
|
rather than standard input.
|
|
.It Fl l Op Ar job ...
|
|
Displays the queue of jobs which are currently awaiting execution.
|
|
If a
|
|
.Ar job
|
|
argument is specified, only the specified jobs will be displayed.
|
|
Unless the user is the superuser, only the user's own jobs will be
|
|
displayed.
|
|
.It Fl m
|
|
Send mail to the user when the job has completed, even if there was no
|
|
output.
|
|
.It Fl q Ar queue
|
|
Uses the specified queue.
|
|
A queue designation consists of a single letter.
|
|
Valid queue designations range from
|
|
.Sy a
|
|
to
|
|
.Sy z
|
|
and
|
|
.Sy A
|
|
to
|
|
.Sy Z .
|
|
The
|
|
.Sy c
|
|
queue is the default for
|
|
.Nm at
|
|
and the
|
|
.Sy E
|
|
queue 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 the user specified the
|
|
.Fl l
|
|
option and
|
|
.Nm at
|
|
is given a specific queue, only jobs pending in that queue will be shown.
|
|
.It Fl r Ar job ...
|
|
Remove the specified job(s) from the
|
|
.Nm at
|
|
queue.
|
|
.It Fl t Ar time_arg
|
|
Specify the job time.
|
|
The argument should be of the form
|
|
.Oo Oo Ar cc Oc Ns Ar yy Oc Ns Ar mmddHHMM Ns Op \&. Ns Ar SS ,
|
|
where the parts of the argument represent the following:
|
|
.Pp
|
|
.Bl -tag -width Ds -compact -offset indent
|
|
.It Ar ccyy
|
|
Year.
|
|
If yy is specified, but cc is not,
|
|
a value for yy between 69 and 99 results in a cc value of 19.
|
|
Otherwise, a cc value of 20 is used.
|
|
.It Ar mm
|
|
Month:
|
|
a number from 1 to 12.
|
|
.It Ar dd
|
|
Day:
|
|
a number from 1 to 31.
|
|
.It Ar HH
|
|
Hour:
|
|
a number from 0 to 23.
|
|
.It Ar MM
|
|
Minute:
|
|
a number from 0 to 59.
|
|
.It Ar SS
|
|
Second:
|
|
a number from 0 to 60
|
|
(permitting a leap second),
|
|
preceded by a period.
|
|
The default is 0.
|
|
.El
|
|
.El
|
|
.Pp
|
|
.Nm at
|
|
allows some moderately complex
|
|
.Ar timespec
|
|
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).
|
|
It is also possible to specify
|
|
.Cm midnight ,
|
|
.Cm noon ,
|
|
or
|
|
.Cm teatime
|
|
(4pm),
|
|
or have a time-of-day suffixed with
|
|
.Cm AM
|
|
or
|
|
.Cm PM
|
|
for running in the morning or the evening.
|
|
To say what day the job will be run,
|
|
give a date in the form
|
|
.Ar \%month-name day
|
|
with an optional
|
|
.Ar year ,
|
|
or giving a date of the form
|
|
.Ar dd.mm.ccyy ,
|
|
.Ar dd.mm.yy ,
|
|
.Ar mm/dd/ccyy ,
|
|
.Ar mm/dd/yy ,
|
|
.Ar mmddccyy ,
|
|
or
|
|
.Ar mmddyy .
|
|
.Pp
|
|
The year may be given as two or four digits.
|
|
If the year is given as two digits, it is taken to occur as soon as
|
|
possible in the future, which may be in the next century \(em
|
|
unless it's last year, in which case it's considered to be
|
|
a typo.
|
|
.Pp
|
|
The specification of a date must follow the specification of
|
|
the time of day.
|
|
A time like
|
|
.Oo Cm now Oc Cm + Ar count time-units
|
|
may be given,
|
|
where the time-units can be
|
|
.Cm minutes ,
|
|
.Cm hours ,
|
|
.Cm days ,
|
|
.Cm weeks ,
|
|
.Cm months ,
|
|
or
|
|
.Cm years
|
|
(the singular forms are also accepted).
|
|
To tell
|
|
.Nm at
|
|
to run the job today or tomorrow,
|
|
suffix the time with
|
|
.Cm today
|
|
or
|
|
.Cm tomorrow .
|
|
The
|
|
.Cm next
|
|
keyword may be used as an alias for
|
|
.Cm + 1 .
|
|
.Pp
|
|
For example, to run a job at 4pm three days from now, use
|
|
.Ic at 4pm + 3 days .
|
|
To run a job at 10:00am on July 31, use
|
|
.Ic at 10am Jul 31 .
|
|
To run a job at 1am tomorrow, use
|
|
.Ic at 1am tomorrow .
|
|
To run a job at midnight in one week's time, use
|
|
.Ic at midnight next week .
|
|
.Pp
|
|
The
|
|
.Nm at
|
|
utility also supports the time format used by
|
|
.Xr touch 1
|
|
(see the
|
|
.Fl t
|
|
option).
|
|
.Pp
|
|
For both
|
|
.Nm at
|
|
and
|
|
.Nm batch ,
|
|
commands are read from standard input (or the file specified
|
|
with the
|
|
.Fl f
|
|
option) and executed.
|
|
The working directory, the environment (except for the variables
|
|
.Ev BASH_VERSINFO ,
|
|
.Ev DISPLAY ,
|
|
.Ev EUID ,
|
|
.Ev GROUPS ,
|
|
.Ev PPID ,
|
|
.Ev SHELLOPTS ,
|
|
.Ev SSH_AGENT_PID ,
|
|
.Ev SSH_AUTH_SOCK ,
|
|
.Ev TERM ,
|
|
.Ev TERMCAP ,
|
|
.Ev UID ,
|
|
and
|
|
.Ev _ ) ,
|
|
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 user ID.
|
|
The user will be mailed standard error and standard output from his
|
|
commands, if any.
|
|
If
|
|
.Nm at
|
|
is executed from a
|
|
.Xr su 1
|
|
shell, the owner of the login shell will receive the mail.
|
|
.Pp
|
|
For non-root users, permission to run
|
|
.Nm
|
|
is determined by the files
|
|
.Pa /var/cron/at.allow
|
|
and
|
|
.Pa /var/cron/at.deny .
|
|
.Em Note :
|
|
these files must be readable by group crontab (if they exist).
|
|
.Pp
|
|
If the file
|
|
.Pa /var/cron/at.allow
|
|
exists, only usernames mentioned in it are allowed to use
|
|
.Nm at .
|
|
If
|
|
.Pa /var/cron/at.allow
|
|
does not exist,
|
|
.Pa /var/cron/at.deny
|
|
is checked.
|
|
Every username not mentioned in it is then allowed to use
|
|
.Nm at .
|
|
If neither exists, only the superuser is allowed to run
|
|
.Nm at .
|
|
.Pp
|
|
An empty
|
|
.Pa /var/cron/at.deny
|
|
means that every user is allowed to use these commands.
|
|
This is the default configuration.
|
|
.Sh FILES
|
|
.Bl -tag -width /var/cron/at.allow -compact
|
|
.It Pa /var/cron/atjobs
|
|
directory containing job files
|
|
.It Pa /var/cron/at.allow
|
|
allow permission control
|
|
.It Pa /var/cron/at.deny
|
|
deny permission control
|
|
.El
|
|
.Sh EXIT STATUS
|
|
The
|
|
.Nm
|
|
utility exits with one of the following values:
|
|
.Pp
|
|
.Bl -tag -width Ds -offset indent -compact
|
|
.It 0
|
|
Jobs were successfully submitted, removed, or listed.
|
|
.It >0
|
|
An error occurred.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr atq 1 ,
|
|
.Xr atrm 1 ,
|
|
.Xr nice 1 ,
|
|
.Xr sh 1 ,
|
|
.Xr touch 1 ,
|
|
.Xr umask 2 ,
|
|
.Xr cron 8
|
|
.Sh STANDARDS
|
|
The
|
|
.Nm
|
|
and
|
|
.Nm batch
|
|
utilities are compliant with the
|
|
.St -p1003.1-2008
|
|
specification.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
flags
|
|
.Op Fl bc
|
|
and the
|
|
.Nm batch
|
|
flags
|
|
.Op Fl fmq ,
|
|
as well as
|
|
the
|
|
.Cm teatime
|
|
keyword,
|
|
are extensions to that specification.
|
|
.Pp
|
|
.St -p1003.1-2008
|
|
states that
|
|
.Nm batch
|
|
jobs are submitted to the queue
|
|
.Qq with no time constraints ;
|
|
this implementation permits a
|
|
.Ar timespec
|
|
argument.
|
|
.Pp
|
|
The at.allow/deny mechanism is marked by
|
|
.St -p1003.1-2008
|
|
as being an
|
|
X/Open System Interfaces
|
|
option.
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
.Nm at
|
|
was mostly written by
|
|
.An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de .
|
|
The time parsing routines are by
|
|
.An David Parsons Aq Mt orc@pell.chi.il.us .
|
|
.Sh BUGS
|
|
.Nm at
|
|
and
|
|
.Nm batch
|
|
as presently implemented are not suitable when users are competing for
|
|
resources.
|
|
If this is the case consider another batch system,
|
|
such as
|
|
.Nm nqs .
|