at.tproj/at.1

   1 .\" $FreeBSD: src/usr.bin/at/at.man,v 1.34 2003/03/26 02:38:18 keramida Exp $
   2 .Dd January 13, 2002
   3 .Dt "AT" 1
   4 .Os
   5 .Sh NAME
   6 .Nm at ,
   7 .Nm batch ,
   8 .Nm atq ,
   9 .Nm atrm
  10 .Nd queue, examine, or delete jobs for later execution
  11 .Sh SYNOPSIS
  12 .Nm at
  13 .Op Fl q Ar queue
  14 .Op Fl f Ar file
  15 .Op Fl mldbv
  16 .Ar time
  17 .Nm at
  18 .Op Fl q Ar queue
  19 .Op Fl f Ar file
  20 .Op Fl mldbv
  21 .Fl t
  22 .Sm off
  23 .Op Oo Ar CC Oc Ar YY
  24 .Ar MM DD hh mm Op . Ar SS
  25 .Sm on
  26 .Nm at
  27 .Fl c Ar job Op Ar job ...
  28 .Nm at
  29 .Fl l Op Ar job ...
  30 .Nm at
  31 .Fl l
  32 .Fl q Ar queue
  33 .Nm at
  34 .Fl r Ar job Op Ar job ...
  35 .Pp
  36 .Nm atq
  37 .Op Fl q Ar queue
  38 .Op Fl v
  39 .Pp
  40 .Nm atrm
  41 .Ar job
  42 .Op Ar job ...
  43 .Pp
  44 .Nm batch
  45 .Op Fl q Ar queue
  46 .Op Fl f Ar file
  47 .Op Fl mv
  48 .Op Ar time
  49 .Sh DESCRIPTION
  50 The
  51 .Nm at
  52 and
  53 .Nm batch
  54 utilities
  55 read commands from standard input or a specified file.
  56 The commands are executed at a later time, using
  57 .Xr sh 1 .
  58 .Bl -tag -width indent
  59 .It Nm at
  60 executes commands at a specified time;
  61 .It Nm atq
  62 lists the user's pending jobs, unless the user is the superuser; in that
  63 case, everybody's jobs are listed;
  64 .It Nm atrm
  65 deletes jobs;
  66 .It Nm batch
  67 executes commands when system load levels permit; in other words, when the load average
  68 drops below _LOADAVG_MX (1.5), or the value specified in the invocation of
  69 .Nm atrun .
  70 .El
  71 .Pp
  72 The
  73 .Nm at
  74 utility allows some moderately complex
  75 .Ar time
  76 specifications.
  77 It accepts times of the form
  78 .Ar HHMM
  79 or
  80 .Ar HH:MM
  81 to run a job at a specific time of day.
  82 (If that time is already past, the next day is assumed.)
  83 As an alternative, the following keywords may be specified:
  84 .Em midnight ,
  85 .Em noon ,
  86 or
  87 .Em teatime
  88 (4pm)
  89 and time-of-day may be suffixed with
  90 .Em AM
  91 or
  92 .Em PM
  93 for running in the morning or the evening.
  94 The day on which the job is to be run may also be specified
  95 by giving a date in the form
  96 .Ar \%month-name day
  97 with an optional
  98 .Ar year ,
  99 or giving a date of the forms
 100 .Ar DD.MM.YYYY ,
 101 .Ar DD.MM.YY ,
 102 .Ar MM/DD/YYYY ,
 103 .Ar MM/DD/YY ,
 104 .Ar MMDDYYYY , or
 105 .Ar MMDDYY .
 106 The specification of a date must follow the specification of
 107 the time of day.
 108 Time can also be specified as:
 109 .Op Em now
 110 .Em + Ar count \%time-units ,
 111 where the time-units can be
 112 .Em minutes ,
 113 .Em hours ,
 114 .Em days ,
 115 .Em weeks ,
 116 .Em months
 117 or
 118 .Em years
 119 and
 120 .Nm at
 121 may be told to run the job today by suffixing the time with
 122 .Em today
 123 and to run the job tomorrow by suffixing the time with
 124 .Em tomorrow .
 125 The shortcut
 126 .Em next
 127 can be used instead of
 128 .Em + 1 .
 129 .Pp
 130 For example, to run a job at 4pm three days from now, use
 131 .Nm at Ar 4pm + 3 days ,
 132 to run a job at 10:00am on July 31, use
 133 .Nm at Ar 10am Jul 31
 134 and to run a job at 1am tomorrow, use
 135 .Nm at Ar 1am tomorrow .
 136 .Pp
 137 The
 138 .Nm at
 139 utility also supports the
 140 .Tn POSIX
 141 time format (see
 142 .Fl t
 143 option).
 144 .Pp
 145 For both
 146 .Nm at
 147 and
 148 .Nm batch ,
 149 commands are read from standard input or the file specified
 150 with the
 151 .Fl f
 152 option.
 153 The working directory, the environment (except for the variables
 154 .Ev TERM ,
 155 .Ev TERMCAP ,
 156 .Ev DISPLAY
 157 and
 158 .Em _ ) ,
 159 and the
 160 .Ar umask
 161 are retained from the time of invocation.
 162 An
 163 .Nm at
 164 or
 165 .Nm batch
 166 command invoked from a
 167 .Xr su 1
 168 shell will retain the current userid.
 169 The user will be mailed standard error and standard output from his
 170 commands, if any.
 171 Mail will be sent using the command
 172 .Xr sendmail 8 .
 173 If
 174 .Nm at
 175 is executed from a
 176 .Xr su 1
 177 shell, the owner of the login shell will receive the mail.
 178 .Pp
 179 The superuser may use these commands in any case.
 180 For other users, permission to use
 181 .Nm at
 182 is determined by the files
 183 .Pa _PERM_PATH/at.allow
 184 and
 185 .Pa _PERM_PATH/at.deny .
 186 .Pp
 187 If the file
 188 .Pa _PERM_PATH/at.allow
 189 exists, only usernames mentioned in it are allowed to use
 190 .Nm at .
 191 In these two files,
 192 a user is considered to be listed
 193 only if the user name has no blank or other characters
 194 before it on its line and a newline character immediately after the name,
 195 even at the end of the file.
 196 Other lines are ignored and may be used for comments.
 197 .Pp
 198 If
 199 .Pa _PERM_PATH/at.allow
 200 does not exist,
 201 .Pa _PERM_PATH/at.deny
 202 is checked, every username not mentioned in it is then allowed
 203 to use
 204 .Nm at .
 205 .Pp
 206 If neither exists, only the superuser is allowed use of
 207 .Nm at .
 208 .Sh IMPLEMENTATION NOTES
 209 Note that
 210 .Nm at
 211 is implemented through the
 212 .Xr launchd 8
 213 daemon periodically invoking
 214 .Xr atrun 8 ,
 215 which is disabled by default.
 216 See
 217 .Xr atrun 8
 218 for information about enabling
 219 .Nm atrun .
 220 .Sh OPTIONS
 221 .Bl -tag -width indent
 222 .It Fl b
 223 Is an alias for
 224 .Nm batch .
 225 .It Fl c
 226 Cat the jobs listed on the command line to standard output.
 227 .It Fl d
 228 Is an alias for
 229 .Nm atrm
 230 (this option is deprecated; use
 231 .Fl r
 232 instead).
 233 .It Fl f Ar file
 234 Read the job from
 235 .Ar file
 236 rather than standard input.
 237 .It Fl l
 238 With no arguments, list all jobs for the invoking user.
 239 If one or more
 240 job numbers are given, list only those jobs.
 241 .It Fl m
 242 Send mail to the user when the job has completed even if there was no
 243 output.
 244 .It Fl q Ar queue
 245 Use the specified queue.
 246 A queue designation consists of a single letter; valid queue designations
 247 range from
 248 .Ar a
 249 to
 250 .Ar z
 251 and
 252 .Ar A
 253 to
 254 .Ar Z .
 255 The
 256 .Ar _DEFAULT_AT_QUEUE
 257 queue (a) is the default for
 258 .Nm at
 259 and the
 260 .Ar _DEFAULT_BATCH_QUEUE
 261 queue (b) is the default for
 262 .Nm batch .
 263 Queues with higher letters run with increased niceness.
 264 If a job is submitted to a queue designated with an uppercase letter, it
 265 is treated as if it had been submitted to batch at that time.
 266 If
 267 .Nm atq
 268 is given a specific queue, it will only show jobs pending in that queue.
 269 .It Fl r
 270 Remove the specified jobs.
 271 .It Fl t
 272 Specify the job time using the \*[Px] time format.
 273 The argument should be in the form
 274 .Sm off
 275 .Op Oo Ar CC Oc Ar YY
 276 .Ar MM DD hh mm Op . Ar SS
 277 .Sm on
 278 where each pair of letters represents the following:
 279 .Pp
 280 .Bl -tag -width indent -compact -offset indent
 281 .It Ar CC
 282 The first two digits of the year (the century).
 283 .It Ar YY
 284 The second two digits of the year.
 285 .It Ar MM
 286 The month of the year, from 1 to 12.
 287 .It Ar DD
 288 the day of the month, from 1 to 31.
 289 .It Ar hh
 290 The hour of the day, from 0 to 23.
 291 .It Ar mm
 292 The minute of the hour, from 0 to 59.
 293 .It Ar SS
 294 The second of the minute, from 0 to 61.
 295 .El
 296 .Pp
 297 If the
 298 .Ar CC
 299 and
 300 .Ar YY
 301 letter pairs are not specified, the values default to the current
 302 year.
 303 If the
 304 .Ar SS
 305 letter pair is not specified, the value defaults to 0.
 306 .It Fl v
 307 For
 308 .Nm atq ,
 309 shows completed but not yet deleted jobs in the queue; otherwise
 310 shows the time the job will be executed.
 311 .El
 312 .Sh FILES
 313 .Bl -tag -width _ATJOB_DIR/_LOCKFILE -compact
 314 .It Pa _ATJOB_DIR
 315 directory containing job files
 316 (/usr/lib/cron/jobs/)
 317 .It Pa _ATJOB_DIR/_LOCKFILE
 318 job-creation lock file
 319 (/usr/lib/cron/jobs/...)
 320 .It Pa _ATSPOOL_DIR
 321 directory containing output spool files
 322 (/usr/lib/cron/spool/)
 323 .It Pa _PERM_PATH/at.allow
 324 allow permission control
 325 (/usr/lib/cron/at.allow)
 326 .It Pa _PERM_PATH/at.deny
 327 deny permission control
 328 (/usr/lib/cron/at.deny)
 329 .It Pa /var/run/utmpx
 330 login records
 331 .El
 332 .Sh SEE ALSO
 333 .Xr nice 1 ,
 334 .Xr sh 1 ,
 335 .Xr umask 2 ,
 336 .Xr compat 5 ,
 337 .Xr atrun 8 ,
 338 .Xr cron 8 ,
 339 .Xr sendmail 8
 340 .Sh BUGS
 341 If the file
 342 .Pa /var/run/utmpx
 343 is not available or corrupted,
 344 or if the user is not logged on at the time
 345 .Nm at
 346 is invoked, the mail is sent to the userid found
 347 in the environment variable
 348 .Ev LOGNAME .
 349 If that is undefined or empty, the current userid is assumed.
 350 .Pp
 351 The
 352 .Nm at
 353 and
 354 .Nm batch
 355 utilities
 356 as presently implemented are not suitable when users are competing for
 357 resources.
 358 If this is the case, another batch system such as
 359 .Em nqs
 360 may be more suitable.
 361 .Pp
 362 Specifying a date past 2038 may not work on some systems.
 363 .Sh AUTHORS
 364 At was mostly written by
 365 .An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de .
 366 The time parsing routines are by
 367 .An David Parsons Aq orc@pell.chi.il.us ,
 368 with minor enhancements by
 369 .An Joe Halpin Aq joe.halpin@attbi.com .