usr.bin/at/at.man

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