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 .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 which are to
  56 be 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, 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
 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
 143 and
 144 .Nm batch ,
 145 commands are read from standard input or the file specified
 146 with the
 147 .Fl f
 148 option and executed.
 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
 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
 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
 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 .
 187 In these two files, a user is considered to be listed only if the user
 188 name has no blank or other characters before it on its line and a
 189 newline character immediately after the name, even at the end of
 190 the file.
 191 Other lines are ignored and may be used for comments.
 192 .Pp
 193 If
 194 .Pa _PERM_PATH/at.allow
 195 does not exist,
 196 .Pa _PERM_PATH/at.deny
 197 is checked, every username not mentioned in it is then allowed
 198 to use
 199 .Nm .
 200 In these two files, a user is considered to be listed only if the user
 201 name has no blank or other characters before it on its line and a
 202 newline character immediately after the name, even at the end of
 203 the file.
 204 Other lines are ignored and may be used for comments.
 205 .Pp
 206 If neither exists, only the superuser is allowed use of
 207 .Nm .
 208 This is the default configuration.
 209 .Sh IMPLEMENTATION NOTES
 210 Note that
 211 .Nm
 212 is implemented through the
 213 .Xr cron 8
 214 daemon by calling
 215 .Xr atrun 8
 216 every five minutes.
 217 This implies that the granularity of
 218 .Nm
 219 might not be optimal for every deployment.
 220 If a finer granularity is needed, the system crontab at
 221 .Pa /etc/crontab
 222 needs to be changed.
 223 .Sh OPTIONS
 224 .Bl -tag -width indent
 225 .It Fl q Ar queue
 226 Use the specified queue.
 227 A queue designation consists of a single letter; valid queue designations
 228 range from
 229 .Ar a
 230 to
 231 .Ar z
 232 and
 233 .Ar A
 234 to
 235 .Ar Z .
 236 The
 237 .Ar _DEFAULT_AT_QUEUE
 238 queue is the default for
 239 .Nm
 240 and the
 241 .Ar _DEFAULT_BATCH_QUEUE
 242 queue for
 243 .Nm batch .
 244 Queues with higher letters run with increased niceness.
 245 If a job is submitted to a queue designated with an uppercase letter, it
 246 is treated as if it had been submitted to batch at that time.
 247 If
 248 .Nm atq
 249 is given a specific queue, it will only show jobs pending in that queue.
 250 .It Fl m
 251 Send mail to the user when the job has completed even if there was no
 252 output.
 253 .It Fl f Ar file
 254 Read the job from
 255 .Ar file
 256 rather than standard input.
 257 .It Fl l
 258 With no arguments, list all jobs for the invoking user.
 259 If one or more
 260 job numbers are given, list only those jobs.
 261 .It Fl d
 262 Is an alias for
 263 .Nm atrm
 264 (this option is deprecated; use
 265 .Fl r
 266 instead).
 267 .It Fl b
 268 Is an alias for
 269 .Nm batch .
 270 .It Fl v
 271 For
 272 .Nm atq ,
 273 shows completed but not yet deleted jobs in the queue; otherwise
 274 shows the time the job will be executed.
 275 .It Fl c
 276 Cat the jobs listed on the command line to standard output.
 277 .It Fl r
 278 Remove the specified jobs.
 279 .It Fl t
 280 Specify the job time using the
 281 .Tn POSIX
 282 time format.
 283 The argument should be in the form
 284 .Sm off
 285 .Op Oo Ar CC Oc Ar YY
 286 .Ar MM DD hh mm Op . Ar SS
 287 .Sm on
 288 where each pair of letters represents the following:
 289 .Pp
 290 .Bl -tag -width indent -compact -offset indent
 291 .It Ar CC
 292 The first two digits of the year (the century).
 293 .It Ar YY
 294 The second two digits of the year.
 295 .It Ar MM
 296 The month of the year, from 1 to 12.
 297 .It Ar DD
 298 the day of the month, from 1 to 31.
 299 .It Ar hh
 300 The hour of the day, from 0 to 23.
 301 .It Ar mm
 302 The minute of the hour, from 0 to 59.
 303 .It Ar SS
 304 The second of the minute, from 0 to 61.
 305 .El
 306 .Pp
 307 If the
 308 .Ar CC
 309 and
 310 .Ar YY
 311 letter pairs are not specified, the values default to the current
 312 year.
 313 If the
 314 .Ar SS
 315 letter pair is not specified, the value defaults to 0.
 316 .El
 317 .Sh FILES
 318 .Bl -tag -width _ATJOB_DIR/_LOCKFILE -compact
 319 .It Pa _ATJOB_DIR
 320 directory containing job files
 321 .It Pa _ATSPOOL_DIR
 322 directory containing output spool files
 323 .It Pa /var/run/utmp
 324 login records
 325 .It Pa _PERM_PATH/at.allow
 326 allow permission control
 327 .It Pa _PERM_PATH/at.deny
 328 deny permission control
 329 .It Pa _ATJOB_DIR/_LOCKFILE
 330 job-creation lock file
 331 .El
 332 .Sh SEE ALSO
 333 .Xr nice 1 ,
 334 .Xr sh 1 ,
 335 .Xr umask 2 ,
 336 .Xr atrun 8 ,
 337 .Xr cron 8 ,
 338 .Xr sendmail 8
 339 .Sh STANDARDS
 340 The
 341 .Nm at
 342 and
 343 .Nm batch
 344 utilities do not conform to
 345 .St -p1003.1-2004 .
 346 .Sh AUTHORS
 347 .An -nosplit
 348 At was mostly written by
 349 .An Thomas Koenig Aq Mt ig25@rz.uni-karlsruhe.de .
 350 The time parsing routines are by
 351 .An David Parsons Aq Mt orc@pell.chi.il.us ,
 352 with minor enhancements by
 353 .An Joe Halpin Aq Mt joe.halpin@attbi.com .
 354 .Sh BUGS
 355 If the file
 356 .Pa /var/run/utmp
 357 is not available or corrupted, or if the user is not logged on at the
 358 time
 359 .Nm
 360 is invoked, the mail is sent to the userid found
 361 in the environment variable
 362 .Ev LOGNAME .
 363 If that is undefined or empty, the current userid is assumed.
 364 .Pp
 365 The
 366 .Nm at
 367 and
 368 .Nm batch
 369 utilities
 370 as presently implemented are not suitable when users are competing for
 371 resources.
 372 If this is the case, another batch system such as
 373 .Em nqs
 374 may be more suitable.
 375 .Pp
 376 Specifying a date past 2038 may not work on some systems.