usr.bin/at/at.man

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