usr.bin/at/at.man

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