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