xref: /dragonfly/usr.bin/at/at.man (revision 1de703da)
1.\" $FreeBSD: src/usr.bin/at/at.man,v 1.13.2.10 2003/05/03 21:55:26 keramida Exp $
2.\" $DragonFly: src/usr.bin/at/at.man,v 1.2 2003/06/17 04:29:25 dillon Exp $
3.Dd April 12, 1995
4.Dt "AT" 1
5.Os
6.Sh NAME
7.Nm at ,
8.Nm batch ,
9.Nm atq ,
10.Nm atrm
11.Nd queue, examine or delete jobs for later execution
12.Sh SYNOPSIS
13.Nm at
14.Op Fl V
15.Op Fl q Ar queue
16.Op Fl f Ar file
17.Op Fl mldbv
18.Ar time
19.Nm at
20.Op Fl V
21.Fl c Ar job Op Ar job ...
22.Pp
23.Nm atq
24.Op Fl V
25.Op Fl q Ar queue
26.Op Fl v
27.Pp
28.Nm atrm
29.Op Fl V
30.Ar job
31.Op Ar job ...
32.Pp
33.Nm batch
34.Op Fl V
35.Op Fl q Ar queue
36.Op Fl f Ar file
37.Op Fl mv
38.Op Ar time
39.Sh DESCRIPTION
40.Nm \&At
41and
42.Nm batch
43read commands from standard input or a specified file which are to
44be executed at a later time, using
45.Xr sh 1 .
46.Bl -tag -width indent
47.It Nm at
48executes commands at a specified time;
49.It Nm atq
50lists the user's pending jobs, unless the user is the superuser; in that
51case, everybody's jobs are listed;
52.It Nm atrm
53deletes jobs;
54.It Nm batch
55executes commands when system load levels permit; in other words, when the load average
56drops below _LOADAVG_MX, or the value specified in the invocation of
57.Nm atrun .
58.El
59.Pp
60.Nm \&At
61allows some moderately complex
62.Ar time
63specifications.
64It accepts times of the form
65.Ar HHMM
66or
67.Ar HH:MM
68to run a job at a specific time of day.
69(If that time is already past, the next day is assumed.)
70As an alternative, the following keywords may be specified:
71.Em midnight ,
72.Em noon ,
73or
74.Em teatime
75(4pm)
76and time-of-day may be suffixed with
77.Em AM
78or
79.Em PM
80for running in the morning or the evening.
81The day on which the job is to be run may also be specified
82by giving a date in the form
83.Ar \%month-name day
84with an optional
85.Ar year ,
86or giving a date of the forms
87.Ar DD.MM.YYYY ,
88.Ar DD.MM.YY ,
89.Ar MM/DD/YYYY ,
90.Ar MM/DD/YY ,
91.Ar MMDDYYYY , or
92.Ar MMDDYY .
93The specification of a date must follow the specification of
94the time of day.
95Time can also be specified as:
96.Op Em now
97.Em + Ar count \%time-units ,
98where the time-units can be
99.Em minutes ,
100.Em hours ,
101.Em days ,
102.Em weeks ,
103.Em months
104or
105.Em years
106and you can tell
107.Nm
108to run the job today by suffixing the time with
109.Em today
110and to run the job tomorrow by suffixing the time with
111.Em tomorrow .
112.Pp
113For example, to run a job at 4pm three days from now, you would do
114.Nm at Ar 4pm + 3 days ,
115to run a job at 10:00am on July 31, you would do
116.Nm at Ar 10am Jul 31
117and to run a job at 1am tomorrow, you would do
118.Nm at Ar 1am tomorrow .
119.Pp
120For both
121.Nm
122and
123.Nm batch ,
124commands are read from standard input or the file specified
125with the
126.Fl f
127option and executed.
128The working directory, the environment (except for the variables
129.Ev TERM ,
130.Ev TERMCAP ,
131.Ev DISPLAY
132and
133.Em _ )
134and the
135.Ar umask
136are retained from the time of invocation.
137An
138.Nm
139or
140.Nm batch
141command invoked from a
142.Xr su 1
143shell will retain the current userid.
144The user will be mailed standard error and standard output from his
145commands, if any.
146Mail will be sent using the command
147.Xr sendmail 8 .
148If
149.Nm
150is executed from a
151.Xr su 1
152shell, the owner of the login shell will receive the mail.
153.Pp
154The superuser may use these commands in any case.
155For other users, permission to use
156.Nm
157is determined by the files
158.Pa _PERM_PATH/at.allow
159and
160.Pa _PERM_PATH/at.deny .
161.Pp
162If the file
163.Pa _PERM_PATH/at.allow
164exists, only usernames mentioned in it are allowed to use
165.Nm .
166In these two files, a user is considered to be listed only if the user
167name has no blank or other characters before it on its line and a
168newline character immediately after the name, even at the end of
169the file.
170Other lines are ignored and may be used for comments.
171.Pp
172If
173.Pa _PERM_PATH/at.allow
174does not exist,
175.Pa _PERM_PATH/at.deny
176is checked, every username not mentioned in it is then allowed
177to use
178.Nm Ns .
179.Pp
180If neither exists, only the superuser is allowed use of
181.Nm Ns .
182This is the default configuration.
183.Sh OPTIONS
184.Bl -tag -width indent
185.It Fl V
186Print the version number to standard error.
187.It Fl q Ar queue
188Use the specified queue.
189A queue designation consists of a single letter; valid queue designations
190range from
191.Ar a
192to
193.Ar z
194and
195.Ar A
196to
197.Ar Z .
198The
199.Ar _DEFAULT_AT_QUEUE
200queue is the default for
201.Nm
202and the
203.Ar _DEFAULT_BATCH_QUEUE
204queue for
205.Nm batch .
206Queues with higher letters run with increased niceness.
207If a job is submitted to a queue designated with an uppercase letter, it
208is treated as if it had been submitted to batch at that time.
209If
210.Nm atq
211is given a specific queue, it will only show jobs pending in that queue.
212.It Fl m
213Send mail to the user when the job has completed even if there was no
214output.
215.It Fl f Ar file
216Read the job from
217.Ar file
218rather than standard input.
219.It Fl l
220Is an alias for
221.Nm atq .
222.It Fl d
223Is an alias for
224.Nm atrm .
225.It Fl b
226Is an alias for
227.Nm batch .
228.It Fl v
229For
230.Nm atq ,
231shows completed but not yet deleted jobs in the queue; otherwise
232shows the time the job will be executed.
233.It Fl c
234Cat the jobs listed on the command line to standard output.
235.El
236.Sh FILES
237.Bl -tag -width _ATJOB_DIR/_LOCKFILE -compact
238.It Pa _ATJOB_DIR
239directory containing job files
240.It Pa _ATSPOOL_DIR
241directory containing output spool files
242.It Pa /var/run/utmp
243login records
244.It Pa _PERM_PATH/at.allow
245allow permission control
246.It Pa _PERM_PATH/at.deny
247deny permission control
248.It Pa _ATJOB_DIR/_LOCKFILE
249job-creation lock file
250.El
251.Sh SEE ALSO
252.Xr nice 1 ,
253.Xr sh 1 ,
254.Xr umask 2 ,
255.Xr atrun 8 ,
256.Xr cron 8 ,
257.Xr sendmail 8
258.Sh BUGS
259If the file
260.Pa /var/run/utmp
261is not available or corrupted, or if the user is not logged on at the
262time
263.Nm
264is invoked, the mail is sent to the userid found
265in the environment variable
266.Ev LOGNAME .
267If that is undefined or empty, the current userid is assumed.
268.Pp
269.Nm \&At
270and
271.Nm batch
272as presently implemented are not suitable when users are competing for
273resources.
274If this is the case for your site, you might want to consider another
275batch system, such as
276.Em nqs .
277.Sh AUTHORS
278At was mostly written by
279.An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de .
280The time parsing routines are by
281.An David Parsons Aq orc@pell.chi.il.us .
282