xref: /freebsd/usr.bin/at/at.man (revision 05c7a37afb48ddd5ee1bd921a5d46fe59cc70b15)
1.\" $Id: at.man,v 1.3 1995/08/21 12:32:47 ache 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 ,
97or
98.Nm weeks
99and you can tell
100.Nm at
101to run the job today by suffixing the time with
102.Nm today
103and to run the job tomorrow by suffixing the time with
104.Nm tomorrow.
105.Pp
106For example, to run a job at 4pm three days from now, you would do
107.Nm at 4pm + 3 days ,
108to run a job at 10:00am on July 31, you would do
109.Nm at 10am Jul 31
110and to run a job at 1am tomorrow, you would do
111.Nm at 1am tomorrow.
112.Pp
113For both
114.Nm at
115and
116.Nm batch ,
117commands are read from standard input or the file specified
118with the
119.Fl f
120option and executed.
121The working directory, the environment (except for the variables
122.Nm TERM ,
123.Nm TERMCAP ,
124.Nm DISPLAY
125and
126.Nm _ )
127and the
128.Ar umask
129are retained from the time of invocation.
130An
131.Nm at
132or
133.Nm batch
134command invoked from a
135.Xr su 1
136shell will retain the current userid.
137The user will be mailed standard error and standard output from his
138commands, if any. Mail will be sent using the command
139.Xr sendmail 8 .
140If
141.Nm at
142is executed from a
143.Xr su 1
144shell, the owner of the login shell will receive the mail.
145.Pp
146The superuser may use these commands in any case.
147For other users, permission to use at is determined by the files
148.Pa _PERM_PATH/at.allow
149and
150.Pa _PERM_PATH/at.deny .
151.Pp
152If the file
153.Pa _PERM_PATH/at.allow
154exists, only usernames mentioned in it are allowed to use
155.Nm at .
156.Pp
157If
158.Pa _PERM_PATH/at.allow
159does not exist,
160.Pa _PERM_PATH/at.deny
161is checked, every username not mentioned in it is then allowed
162to use
163.Nm at .
164.Pp
165If neither exists, only the superuser is allowed use of
166.Nm at .
167This is the default configuration.
168.Pp
169An empty
170.Pa _PERM_PATH/at.deny
171means that every user is allowed use these commands.
172.Sh OPTIONS
173.Bl -tag -width indent
174.It Fl V
175prints the version number to standard error.
176.It Fl q Ar queue
177uses the specified queue.
178A queue designation consists of a single letter; valid queue designations
179range from
180.Nm a
181to
182.Nm z .
183and
184.Nm A
185to
186.Nm Z .
187The
188.Nm _DEFAULT_AT_QUEUE
189queue is the default for
190.Nm at
191and the
192.Nm _DEFAULT_BATCH_QUEUE
193queue for
194.Nm batch .
195Queues with higher letters run with increased niceness.
196If a job is submitted to a queue designated with an uppercase letter, it
197is treated as if it had been submitted to batch at that time.
198If
199.Nm atq
200is given a specific queue, it will only show jobs pending in that queue.
201.It Fl m
202Send mail to the user when the job has completed even if there was no
203output.
204.It Fl f Ar file
205Reads the job from
206.Ar file
207rather than standard input.
208.It Fl l
209Is an alias for
210.Nm atq.
211.It Fl d
212Is an alias for
213.Nm atrm.
214.It Fl b
215Is an alias for
216.Nm batch.
217.It Fl v
218For
219.Nm atq ,
220shows completed but not yet deleted jobs in the queue; otherwise
221shows the time the job will be executed.
222.It Fl c
223Cats the jobs listed on the command line to standart output.
224.Sh FILES
225.Bl -tag -width _ATJOB_DIR/_LOCKFILE -compact
226.It Pa _ATJOB_DIR
227Directory containing job files
228.It Pa _ATSPOOL_DIR
229Directory containing output spool files
230.It Pa /var/run/utmp
231Login records
232.It Pa _PERM_PATH/at.allow
233Allow permission control
234.It Pa _PERM_PATH/at.deny
235Deny permission control
236.It Pa _ATJOB_DIR/_LOCKFILE
237Job-creation lock file.
238.Sh SEE ALSO
239.Xr cron 8 ,
240.Xr nice 1 ,
241.Xr umask 2 ,
242.Xr sh 1 ,
243.Xr sendmail 8 ,
244.Xr atrun 8 .
245.El
246.Sh BUGS
247.Pp
248If the file
249.Pa /var/run/utmp
250is not available or corrupted, or if the user is not logged on at the
251time
252.Nm at
253is invoked, the mail is sent to the userid found
254in the environment variable
255.Nm LOGNAME .
256If that is undefined or empty, the current userid is assumed.
257.Pp
258.Nm At
259and
260.Nm batch
261as presently implemented are not suitable when users are competing for
262resources.
263If this is the case for your site, you might want to consider another
264batch system, such as
265.Nm nqs .
266.Sh AUTHOR
267At was mostly written by Thomas Koenig, ig25@rz.uni-karlsruhe.de.
268The time parsing routines are by David Parsons, orc@pell.chi.il.us.
269