[src/trunk]: src/external/bsd/cron/dist Replace with the OpenBSD man page. It...

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/f1ab123985df
branches:  trunk
changeset: 323424:f1ab123985df
user:      christos <christos%NetBSD.org@localhost>
date:      Thu Jun 14 22:02:57 2018 +0000

description:
Replace with the OpenBSD man page. It removes some historical comparisons
that are not very useful (and trully if any they belong to a separate section
instead of being interspersed in the document), and organizes and formats
the information better.

diffstat:

 external/bsd/cron/dist/crontab.5 |  593 ++++++++++++++++++++------------------
 1 files changed, 311 insertions(+), 282 deletions(-)

diffs (truncated from 667 to 300 lines):

diff -r e74c1e71e77d -r f1ab123985df external/bsd/cron/dist/crontab.5
--- a/external/bsd/cron/dist/crontab.5  Thu Jun 14 21:57:25 2018 +0000
+++ b/external/bsd/cron/dist/crontab.5  Thu Jun 14 22:02:57 2018 +0000
@@ -1,25 +1,27 @@
-.\"    $NetBSD: crontab.5,v 1.5 2014/03/18 18:20:36 riastradh Exp $
+.\" $NetBSD: crontab.5,v 1.6 2018/06/14 22:02:57 christos Exp $
 .\"
 .\"/* Copyright 1988,1990,1993,1994 by Paul Vixie
 .\" * All rights reserved
-.\" *
-.\" * Distribute freely, except: don't remove my name from the source or
-.\" * documentation (don't take credit for my work), mark your changes (don't
-.\" * get me blamed for your possible bugs), don't alter or remove this
-.\" * notice.  May be sold if buildable source is provided to buyer.  No
-.\" * warrantee of any kind, express or implied, is included with this
-.\" * software; use at your own risk, responsibility for damages (if any) to
-.\" * anyone resulting from the use of this software rests entirely with the
-.\" * user.
-.\" *
-.\" * Send bug reports, bug fixes, enhancements, requests, flames, etc., and
-.\" * I'll try to keep a version up to date.  I can be reached as follows:
-.\" * Paul Vixie          <paul%vix.com@localhost>          uunet!decwrl!vixie!paul
 .\" */
 .\"
-.\" Id: crontab.5,v 2.4 1994/01/15 20:43:43 vixie Exp
+.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
+.\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.Dd July 15, 2010
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
+.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" $OpenBSD: crontab.5,v 1.36 2018/06/13 13:27:37 jmc Exp $
+.\"
+.Dd June 14 2018
 .Dt CRONTAB 5
 .Os
 .Sh NAME
@@ -31,117 +33,241 @@
 file contains instructions to the
 .Xr cron 8
 daemon of the general form:
-.Dq run this command at this time on this date .
-Each user has their own crontab, and commands in any given crontab
-will be executed as the user who owns the crontab.
-Uucp and News will usually have their own crontabs, eliminating
-the need for explicitly running
-.Xr su 1
-as part of a cron command.
+.Dq at these times on these dates run this command .
+There may be a system
+.Nm
+and each user may have their own
+.Nm .
+Commands in any given
+.Nm
+will be
+executed either as the user who owns the
+.Nm
+or, in the case of the system
+.Nm crontab ,
+as the user specified on the command line.
 .Pp
-Blank lines and leading spaces and tabs are ignored.
-Lines whose first non-space character is a pound-sign
-.Pq Sq #
+While a
+.Nm
+is a text file, it is not intended to be directly edited.
+Creation, modification, and removal of a
+.Nm
+should be done using
+.Xr crontab 1 .
+.Pp
+Blank lines, leading spaces, and tabs are ignored.
+Lines whose first non-space character is a pound sign
+.Pq Ql #
 are comments, and are ignored.
-Note that comments are not allowed on the same line as cron commands, since
+Note that comments are not allowed on the same line as
+.Xr cron 8
+commands, since
 they will be taken to be part of the command.
 Similarly, comments are not
 allowed on the same line as environment variable settings.
 .Pp
-An active line in a crontab will be either an environment setting
-or a cron command.
-An environment setting is of the form,
-.Bd -literal
-    name = value
-.Ed
-where the spaces around the equal-sign
-.Pq Sq =
+An active line in a
+.Nm
+is either an environment variable setting or a
+.Xr cron 8
+command.
+.Pp
+Environment variable settings create the environment
+any command in the
+.Nm
+is run in.
+An environment variable setting is of the form:
+.Pp
+.Dl name = value
+.Pp
+The spaces around the equal sign
+.Pq Ql =
 are optional, and any subsequent non-leading spaces in
 .Ar value
 will be part of the value assigned to
 .Ar name .
 The
 .Ar value
-string may be placed in quotes (single or double, but matching) to
-preserve leading or trailing blanks.
-The
-.Ar name
-string may also be placed in quotes (single or double, but matching)
-to preserve leading, trailing or inner blanks.
+string may be placed in quotes
+.Pq single or double , but matching
+to preserve leading or trailing blanks.
+.Pp
+Lines in the system
+.Nm
+have six fixed fields plus a command, in the form:
+.Bd -ragged -offset indent
+.Ar minute
+.Ar hour
+.Ar day-of-month
+.Ar month
+.Ar day-of-week
+.Ar user
+.Ar command
+.Ed
+.Pp
+While lines in a user
+.Nm
+have five fixed fields plus a command, in the form:
+.Bd -ragged -offset indent
+.Ar minute
+.Ar hour
+.Ar day-of-month
+.Ar month
+.Ar day-of-week
+.Ar command
+.Ed
 .Pp
-Several environment variables are set up automatically by the
-.Xr cron 8
-daemon.
-.Ev SHELL
-is set to
-.Pa /bin/sh ,
-and
-.Ev LOGNAME
-and
-.Ev HOME
-are set from the
-.Pa /etc/passwd
-line of the crontab's owner.
-.Ev HOME
-and
-.Ev SHELL
-may be overridden by settings in the crontab;
-.Ev LOGNAME
-may not.
+Fields are separated by blanks or tabs.
+The command may be one or more fields long.
+The allowed values for the fields are:
+.Bl -column "day-of-month" "allowed values" -offset indent
+.It Sy field Ta Sy allowed values
+.It Ar minute Ta * or 0\(en59
+.It Ar hour Ta * or 0\(en23
+.It Ar day-of-month Ta * or 1\(en31
+.It Ar month Ta * or 1\(en12 or a name (see below)
+.It Ar day-of-week Ta * or 0\(en7 or a name (0 or 7 is Sunday)
+.It Ar user Ta a valid username
+.It Ar command Ta text
+.El
+.Pp
+Lists are allowed.
+A list is a set of numbers (or ranges) separated by commas.
+For example,
+.Dq 1,2,5,9
+or
+.Dq 0\(en4,8\(en12 .
+.Pp
+Ranges of numbers are allowed.
+Ranges are two numbers separated with a hyphen.
+The specified range is inclusive.
+For example,
+8\(en11 for an
+.Ar hour
+entry specifies execution at hours 8, 9, 10 and 11.
+.Pp
+Step values can be used in conjunction with ranges.
+Following a range with
+.No / Ns Ar number
+specifies skips of
+.Ar number
+through the range.
+For example,
+.Dq 0\(en23/2
+can be used in the
+.Ar hour
+field to specify command execution every other hour.
+Steps are also permitted after an asterisk, so to say
+.Dq every two hours ,
+just use
+.Dq */2 .
+.Pp
+An asterisk
+.Pq Ql *
+is short form for a range of all allowed values.
 .Pp
-(Another note: the
-.Ev LOGNAME
-variable is sometimes called
-.Ev USER
-on BSD systems...  on these systems,
-.Ev USER
-will be set also.)
+Names can be used in the
+.Ar month
+and
+.Ar day-of-week
+fields.
+Use the first three letters of the particular
+day or month (case doesn't matter).
+Ranges or lists of names are not allowed.
 .Pp
-In addition to
-.Ev LOGNAME ,
-.Ev HOME ,
-and
-.Ev SHELL ,
+The
+.Ar command
+field (the rest of the line) is the command to be
+run.
+The entire command portion of the line, up to a newline or %
+character, will be executed by
+.Pa /bin/sh
+or by the shell
+specified in the
+.Ev SHELL
+variable of the
+.Nm crontab .
+Percent signs
+.Pq Ql %
+in the command, unless escaped with a backslash
+.Pq Ql \e ,
+will be changed into newline characters, and all data
+after the first
+.Ql %
+will be sent to the command as standard input.
+.Pp
+Commands may be modified as follows:
+.Bl -tag -width Ds
+.It Fl n Ar command
+No mail is sent after a successful run.
+The execution output will only be mailed if the command exits with a non-zero
+exit code.
+The
+.Fl n
+option is an attempt to cure potentially copious volumes of mail coming from
+.Xr cron 8 .
+.It Fl q Ar command
+Execution will not be logged.
+.El
+.Pp
+Commands are executed by
 .Xr cron 8
-will look at
-.Ev MAILTO
-if it has any reason to send mail as a result of running commands in
-.Dq this
-crontab.
-If
-.Ev MAILTO
-is defined (and non-empty), mail is sent to the user so named.
-If
-.Ev MAILTO
-is defined but empty
-.Pq Ev MAILTO Ns = Ns \&"" ,
-no mail will be sent.
-Otherwise mail is sent to the owner of the crontab.