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 .Pp
 126 For example, to run a job at 4pm three days from now, use
 127 .Nm at Ar 4pm + 3 days ,
 128 to run a job at 10:00am on July 31, use
 129 .Nm at Ar 10am Jul 31
 130 and to run a job at 1am tomorrow, use
 131 .Nm at Ar 1am tomorrow .
 132 .Pp
 133 The
 134 .Nm at
 135 utility also supports the
 136 .Tn POSIX
 137 time format (see
 138 .Fl t
 139 option).
 140 .Pp
 141 For both
 142 .Nm at
 143 and
 144 .Nm batch ,
 145 commands are read from standard input or the file specified
 146 with the
 147 .Fl f
 148 option.
 149 The working directory, the environment (except for the variables
 150 .Ev TERM ,
 151 .Ev TERMCAP ,
 152 .Ev DISPLAY
 153 and
 154 .Em _ ) ,
 155 and the
 156 .Ar umask
 157 are retained from the time of invocation.
 158 An
 159 .Nm at
 160 or
 161 .Nm batch
 162 command invoked from a
 163 .Xr su 1
 164 shell will retain the current userid.
 165 The user will be mailed standard error and standard output from his
 166 commands, if any.
 167 Mail will be sent using the command
 168 .Xr sendmail 8 .
 169 If
 170 .Nm at
 171 is executed from a
 172 .Xr su 1
 173 shell, the owner of the login shell will receive the mail.
 174 .Pp
 175 The superuser may use these commands in any case.
 176 For other users, permission to use
 177 .Nm at
 178 is determined by the files
 179 .Pa _PERM_PATH/at.allow
 180 and
 181 .Pa _PERM_PATH/at.deny .
 182 .Pp
 183 If the file
 184 .Pa _PERM_PATH/at.allow
 185 exists, only usernames mentioned in it are allowed to use
 186 .Nm at .
 187 In these two files,
 188 a user is considered to be listed
 189 only if the user name has no blank or other characters
 190 before it on its line and a newline character immediately after the name,
 191 even at the end of the file.
 192 Other lines are ignored and may be used for comments.
 193 .Pp
 194 If
 195 .Pa _PERM_PATH/at.allow
 196 does not exist,
 197 .Pa _PERM_PATH/at.deny
 198 is checked, every username not mentioned in it is then allowed
 199 to use
 200 .Nm at .
 201 .Pp
 202 If neither exists, only the superuser is allowed use of
 203 .Nm at .
 204 .Sh IMPLEMENTATION NOTES
 205 Note that
 206 .Nm at
 207 is implemented through the
 208 .Xr launchd 8
 209 daemon periodically invoking
 210 .Xr atrun 8 ,
 211 which is disabled by default.
 212 See
 213 .Xr atrun 8
 214 for information about enabling
 215 .Nm atrun .
 216 .Sh OPTIONS
 217 .Bl -tag -width indent
 218 .It Fl b
 219 Is an alias for
 220 .Nm batch .
 221 .It Fl c
 222 Cat the jobs listed on the command line to standard output.
 223 .It Fl d
 224 Is an alias for
 225 .Nm atrm
 226 (this option is deprecated; use
 227 .Fl r
 228 instead).
 229 .It Fl f Ar file
 230 Read the job from
 231 .Ar file
 232 rather than standard input.
 233 .It Fl l
 234 With no arguments, list all jobs for the invoking user.
 235 If one or more
 236 job numbers are given, list only those jobs.
 237 .It Fl m
 238 Send mail to the user when the job has completed even if there was no
 239 output.
 240 .It Fl q Ar queue
 241 Use the specified queue.
 242 A queue designation consists of a single letter; valid queue designations
 243 range from
 244 .Ar a
 245 to
 246 .Ar z
 247 and
 248 .Ar A
 249 to
 250 .Ar Z .
 251 The
 252 .Ar _DEFAULT_AT_QUEUE
 253 queue (a) is the default for
 254 .Nm at
 255 and the
 256 .Ar _DEFAULT_BATCH_QUEUE
 257 queue (b) is the default for
 258 .Nm batch .
 259 Queues with higher letters run with increased niceness.
 260 If a job is submitted to a queue designated with an uppercase letter, it
 261 is treated as if it had been submitted to batch at that time.
 262 If
 263 .Nm atq
 264 is given a specific queue, it will only show jobs pending in that queue.
 265 .It Fl r
 266 Remove the specified jobs.
 267 .It Fl t
 268 Specify the job time using the \*[Px] time format.
 269 The argument should be in the form
 270 .Sm off
 271 .Op Oo Ar CC Oc Ar YY
 272 .Ar MM DD hh mm Op . Ar SS
 273 .Sm on
 274 where each pair of letters represents the following:
 275 .Pp
 276 .Bl -tag -width indent -compact -offset indent
 277 .It Ar CC
 278 The first two digits of the year (the century).
 279 .It Ar YY
 280 The second two digits of the year.
 281 .It Ar MM
 282 The month of the year, from 1 to 12.
 283 .It Ar DD
 284 the day of the month, from 1 to 31.
 285 .It Ar hh
 286 The hour of the day, from 0 to 23.
 287 .It Ar mm
 288 The minute of the hour, from 0 to 59.
 289 .It Ar SS
 290 The second of the minute, from 0 to 61.
 291 .El
 292 .Pp
 293 If the
 294 .Ar CC
 295 and
 296 .Ar YY
 297 letter pairs are not specified, the values default to the current
 298 year.
 299 If the
 300 .Ar SS
 301 letter pair is not specified, the value defaults to 0.
 302 .It Fl v
 303 For
 304 .Nm atq ,
 305 shows completed but not yet deleted jobs in the queue; otherwise
 306 shows the time the job will be executed.
 307 .El
 308 .Sh FILES
 309 .Bl -tag -width _ATJOB_DIR/_LOCKFILE -compact
 310 .It Pa _ATJOB_DIR
 311 directory containing job files
 312 (/usr/lib/cron/jobs/)
 313 .It Pa _ATJOB_DIR/_LOCKFILE
 314 job-creation lock file
 315 (/usr/lib/cron/jobs/...)
 316 .It Pa _ATSPOOL_DIR
 317 directory containing output spool files
 318 (/usr/lib/cron/spool/)
 319 .It Pa _PERM_PATH/at.allow
 320 allow permission control
 321 (/usr/lib/cron/at.allow)
 322 .It Pa _PERM_PATH/at.deny
 323 deny permission control
 324 (/usr/lib/cron/at.deny)
 325 .It Pa /var/run/utmpx
 326 login records
 327 .El
 328 .Sh SEE ALSO
 329 .Xr nice 1 ,
 330 .Xr sh 1 ,
 331 .Xr umask 2 ,
 332 .Xr compat 5 ,
 333 .Xr atrun 8 ,
 334 .Xr cron 8 ,
 335 .Xr sendmail 8
 336 .Sh BUGS
 337 If the file
 338 .Pa /var/run/utmpx
 339 is not available or corrupted,
 340 or if the user is not logged on at the time
 341 .Nm at
 342 is invoked, the mail is sent to the userid found
 343 in the environment variable
 344 .Ev LOGNAME .
 345 If that is undefined or empty, the current userid is assumed.
 346 .Pp
 347 The
 348 .Nm at
 349 and
 350 .Nm batch
 351 utilities
 352 as presently implemented are not suitable when users are competing for
 353 resources.
 354 If this is the case, another batch system such as
 355 .Em nqs
 356 may be more suitable.
 357 .Pp
 358 Specifying a date past 2038 may not work on some systems.
 359 .Sh AUTHORS
 360 At was mostly written by
 361 .An Thomas Koenig Aq ig25@rz.uni-karlsruhe.de .
 362 The time parsing routines are by
 363 .An David Parsons Aq orc@pell.chi.il.us ,
 364 with minor enhancements by
 365 .An Joe Halpin Aq joe.halpin@attbi.com .