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