Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 407 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man5/crontab.5 b/upstream/debian-unstable/man5/crontab.5
new file mode 100644
index 00000000..b3f3d158
--- /dev/null
+++ b/upstream/debian-unstable/man5/crontab.5
@@ -0,0 +1,407 @@
+.\"/* 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>          uunet!decwrl!vixie!paul
+.\" */
+.\"
+.\" $Id: crontab.5,v 2.4 1994/01/15 20:43:43 vixie Exp $
+.\"
+.TH CRONTAB 5 "19 April 2010"
+.UC 4
+.SH NAME
+crontab \- tables for driving cron
+.SH DESCRIPTION
+A
+.I crontab
+file contains instructions to the
+.IR cron (8)
+daemon of the general form: ``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
+.IR su (1)
+as part of a cron command.
+.PP
+Note that comments on the same line as cron commands are not interpreted as
+comments in the cron sense, but are considered part of the command and passed
+to the shell. This is similarly true for comments 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,
+.PP
+    name = value
+.PP
+where the spaces around the equal-sign (=) are optional, and any subsequent
+non-leading spaces in
+.I value
+will be part of the value assigned to
+.IR name .
+The
+.I value
+string may be placed in quotes (single or double, but matching) to preserve
+leading or trailing blanks.  To define an empty variable, quotes
+.B must
+be used.
+.PP
+The
+.I value
+string is
+.B not
+parsed for environmental substitutions or replacement of variables or
+tilde(~) expansion, thus lines like
+.PP
+.in +4n
+.nf
+PATH=$HOME/bin:$PATH
+PATH=~/bin:/usr/bin
+.fi
+.in
+.PP
+will not work as you might expect. And neither will this work
+.PP
+.in +4n
+.nf
+A=1
+B=2
+C=$A $B
+.fi
+.in
+.PP
+There will not be any substitution for the defined variables in the
+last value. However, with most shells you can also try e.g.,:
+.PP
+     P=PATH=/a/b/c:$PATH
+     33 22 1 2 3 eval $P && some commands
+.PP
+Several environment variables are set up automatically by the
+.IR cron (8)
+daemon.
+SHELL is set to /usr/bin/sh, and LOGNAME and HOME are set from the /etc/passwd
+line of the crontab's owner.
+HOME and SHELL may be overridden by settings in the crontab; LOGNAME may not.
+.PP
+(Another note: the LOGNAME variable is sometimes called USER on BSD systems...
+on these systems, USER will be set also.)
+.PP
+In addition to LOGNAME, HOME, and SHELL,
+.IR cron (8)
+will look at MAILTO if it has any reason to send mail as a result of running
+commands in ``this'' crontab.  If MAILTO is defined (and non-empty), mail is
+sent to the user so named.  If MAILTO is defined but empty (MAILTO=""), no
+mail will be sent.  Otherwise mail is sent to the owner of the crontab.  This
+option is useful if you decide on /usr/bin/mail instead of /usr/lib/sendmail as
+your mailer when you install cron -- /usr/bin/mail doesn't do aliasing, and UUCP
+usually doesn't read its mail.
+.PP
+The format of a cron command is very much the V7 standard, with a number of
+upward-compatible extensions.  Each line has five time and date fields,
+followed by a command, followed by a newline character ('\en').
+The system crontab (/etc/crontab) uses the same format, except that
+the username for the command is specified after the time and
+date fields and before the command.  The fields may be separated
+by spaces or tabs.  The maximum permitted length for the command field is
+998 characters.
+.PP
+Commands are executed by
+.IR cron (8)
+when the minute, hour, and month of year fields match the current time,
+.I and
+when at least one of the two day fields (day of month, or day of week)
+match the current time (see ``Note'' below).
+.IR cron (8)
+examines cron entries once every minute.
+The time and date fields are:
+.IP
+.ta 1.5i
+field	allowed values
+.br
+-----	--------------
+.br
+minute	0-59
+.br
+hour	0-23
+.br
+day of month	0-31
+.br
+month	0-12 (or names, see below)
+.br
+day of week	0-7 (0 or 7 is Sun, or use names)
+.br
+.PP
+A field may be an asterisk (*), which always stands for ``first\-last''.
+.PP
+Ranges of numbers are allowed.  Ranges are two numbers separated
+with a hyphen.  The specified range is inclusive.  For example,
+8-11 for an ``hours'' entry specifies execution at hours 8, 9, 10
+and 11.
+.PP
+Lists are allowed.  A list is a set of numbers (or ranges)
+separated by commas.  Examples: ``1,2,5,9'', ``0-4,8-12''.
+.PP
+Step values can be used in conjunction with ranges.  Following
+a range with ``/<number>'' specifies skips of the number's value
+through the range.  For example, ``0-23/2'' can be used in the hours
+field to specify command execution every other hour (the alternative
+in the V7 standard is ``0,2,4,6,8,10,12,14,16,18,20,22'').  Steps are
+also permitted after an asterisk, so if you want to say ``every two
+hours'', just use ``*/2''.
+.PP
+Names can also be used for the ``month'' and ``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
+The ``sixth'' field (the rest of the line) specifies the command to be
+run.
+The entire command portion of the line, up to a newline or %
+character, will be executed by /usr/bin/sh or by the shell
+specified in the SHELL variable of the cronfile.
+Percent-signs (%) in the command, unless escaped with backslash
+(\\), will be changed into newline characters, and all data
+after the first % will be sent to the command as standard
+input.
+.PP
+Note: The day of a command's execution can be specified by two
+fields \(em day of month, and day of week.  If both fields are
+restricted (i.e., aren't *), the command will be run when
+.I either
+field matches the current time.  For example,
+.br
+``30 4 1,15 * 5''
+would cause a command to be run at 4:30 am on the 1st and 15th of each
+month, plus every Friday.  One can, however, achieve the desired result
+by adding a test to the command (see the last example in EXAMPLE CRON FILE
+below).
+.PP
+Instead of the first five fields, one of eight special strings may appear:
+.IP
+.ta 1.5i
+string	meaning
+.br
+------	-------
+.br
+@reboot	Run once, at startup.
+.br
+@yearly	Run once a year, "0 0 1 1 *".
+.br
+@annually	(same as @yearly)
+.br
+@monthly	Run once a month, "0 0 1 * *".
+.br
+@weekly	Run once a week, "0 0 * * 0".
+.br
+@daily	Run once a day, "0 0 * * *".
+.br
+@midnight	(same as @daily)
+.br
+@hourly	Run once an hour, "0 * * * *".
+.br
+.PP
+Please note that startup, as far as @reboot is concerned, is the time when
+the
+.IR cron (8)
+daemon startup.  In particular, it may be before some system daemons,
+or other facilities, were startup.  This is due to the boot order
+sequence of the machine.
+
+.SH EXAMPLE CRON FILE
+.nf
+
+# use /usr/bin/sh to run commands, no matter what /etc/passwd says
+SHELL=/usr/bin/sh
+# mail any output to `paul', no matter whose crontab this is
+MAILTO=paul
+#
+# run five minutes after midnight, every day
+5 0 * * *       $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
+# run at 2:15pm on the first of every month -- output mailed to paul
+15 14 1 * *     $HOME/bin/monthly
+# run at 10 pm on weekdays, annoy Joe
+0 22 * * 1\-5    mail \-s "It's 10pm" joe%Joe,%%Where are your kids?%
+23 0\-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
+5 4 * * sun     echo "run at 5 after 4 every Sunday"
+0 */4 1 * mon   echo "run every 4th hour on the 1st and on every Monday"
+0 0 */2 * sun   echo "run at midn on every Sunday that's an uneven date"
+# Run on every second Saturday of the month
+0 4 8\-14 * *    test $(date +\e%u) \-eq 6 && echo "2nd Saturday"
+# Same thing, efficient too:
+0 4 * * * Sat   d=$(date +\%e) && test $d -ge 8 -a $d -le 14 && echo "2nd Saturday"
+#Execute early the next morning following the first
+#Thursday of each month
+57 2 * * 5 case $(date +\%d) in 0[2-8]) echo "After 1st Thursday"; esac
+.fi
+
+.PP
+All the above examples run non-interactive programs.  If you wish to run a
+program that interacts with the user's desktop you have to make sure the proper
+environment variable
+.I DISPLAY
+is set.
+
+.\" Note: Based on some web searches, below example might not fully
+.\" work in all systems, as notify-send might require also
+.\" to have knowledge of the dbus session in use (through the environment)
+.\" However, adding that code here is an overkill
+.nf
+# Execute a program and run a notification every day at 10:00 am
+0 10 * * *  $HOME/bin/program | DISPLAY=:0 notify-send "Program run" "$(cat)"
+.fi
+
+.SH EXAMPLE SYSTEM CRON FILE
+
+The following lists the content of a regular system-wide crontab file.  Unlike a
+user's crontab, this file has the username field, as used by /etc/crontab.
+
+.nf
+# /etc/crontab: system-wide crontab
+# Unlike any other crontab you don't have to run the `crontab'
+# command to install the new version when you edit this file
+# and files in /etc/cron.d.  These files also have username fields,
+# that none of the other crontabs do.
+
+SHELL=/bin/sh
+PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
+
+# Example of job definition:
+# .---------------- minute (0 - 59)
+# |  .------------- hour (0 - 23)
+# |  |  .---------- day of month (1 - 31)
+# |  |  |  .------- month (1 - 12) OR jan,feb,mar,apr ...
+# |  |  |  |  .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat
+# |  |  |  |  |
+# m h dom mon dow user	command
+17 * * * *  root  cd / && run-parts \-\-report /etc/cron.hourly
+25 6 * * *  root  test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.daily )
+47 6 * * 7  root  test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.weekly )
+52 6 1 * *  root  test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.monthly )
+#
+.fi
+
+Note that all the system-wide tasks will run, by default, from 6 am to 7 am.  In
+the case of systems that are not powered on during that period of time, only
+the hourly tasks will be executed unless the defaults above are changed.
+
+.SH YET ANOTHER EXAMPLE
+
+In that example one can see that numbers can be prepended some 0, in order
+to line up columns.
+
+.nf
+17  * * * *  root  cd / && run-parts --report /etc/cron.hourly
+25 16 * * *  root  test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.daily )
+47 06 * * 7  root  test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.weekly )
+52 06 1 * *  root  test -x /usr/sbin/anacron || ( cd / && run-parts --report /etc/cron.monthly )
+.fi
+
+.SH SEE ALSO
+cron(8), crontab(1)
+.SH EXTENSIONS
+When specifying day of week, both day 0 and day 7 will be considered Sunday.
+BSD and AT&T seem to disagree about this.
+.PP
+Lists and ranges are allowed to co-exist in the same field.  "1-3,7-9" would
+be rejected by AT&T or BSD cron -- they want to see "1-3" or "7,8,9" ONLY.
+.PP
+Ranges can include "steps", so "1-9/2" is the same as "1,3,5,7,9".
+.PP
+Names of monts or days of the week can be specified by name.
+.PP
+Environment variables can be set in the crontab.  In BSD or AT&T, the
+environment handed to child processes is basically the one from /etc/rc.
+.PP
+Command output is mailed to the crontab owner (BSD can't do this), can be
+mailed to a person other than the crontab owner (SysV can't do this), or the
+feature can be turned off and no mail will be sent at all (SysV can't do this
+either).
+.PP
+All of the `@' commands that can appear in place of the first five fields
+are extensions.
+.SH LIMITATIONS
+The
+.I cron
+daemon runs with a defined timezone.  It currently does not support
+per-user timezones.  All the tasks: system's and user's will be run based on the
+configured timezone.  Even if a user specifies the
+.I TZ
+environment variable in his
+.I crontab
+this will affect only the commands executed in the crontab, not the execution
+of the crontab tasks themselves. If one wants to specify a particular
+timezone for crontab tasks, one may check the date in the child script,
+for example:
+
+.nf
+    # m h  dom mon dow   command
+
+    TZ=UTC
+    0 * * * * [ "$(date +\e%R)" = 00:00 ] && run_some_script
+.fi
+
+POSIX specifies that the day of month and the day of week fields both need to
+match the current time if either of them
+.I is
+a *.  However, this implementation only checks if the
+.I first character
+is a *.  This is why "0 0 */2 * sun" runs every Sunday that's an
+uneven date while the POSIX standard would have it run every Sunday and on
+every uneven date.
+
+The
+.I crontab
+syntax does not make it possible to define all possible periods one can
+imagine.  For example, it is not straightforward to define the last
+weekday of a month.
+To have a task run in a time period that cannot be defined using
+.I crontab
+syntax, the best approach would be to have the program itself check the
+date and time information and continue execution only if the period
+matches the desired one.
+
+If the program itself cannot do the checks then a wrapper script would be
+required.  Useful tools that could be used for date analysis are
+.I ncal
+or
+.I calendar
+For example, to run a program the last Saturday of every month you could use
+the following wrapper code:
+
+.nf
+0 4 * * Sat   [ "$(date +\e%e)" = "$(LANG=C ncal | sed \-n 's/^Sa .* \e([0\-9]\e+\e) *$/\e1/p')" ] && echo "Last Saturday" && program_to_run
+.fi
+
+.SH USING EVAL TO WRAP MISC ENVIRONMENT SETTINGS
+The following tip is kindly provided by 積丹尼 Dan Jacobson:
+.PP
+     CONTENT_TYPE="text/plain; charset=UTF-8"
+     d=eval LANG=zh_TW.UTF-8 w3m -dump
+     26 22 16 1-12 * $d https://www.ptt.cc/bbs/transgender/index.html
+.PP
+ it won't work without the eval. Saying
+ d=LANG=zh_TW.UTF-8 w3m -dump
+ will get
+ /bin/sh: LANG=zh_TW.UTF-8: command not found
+
+.SH DIAGNOSTICS
+cron requires that each entry in a crontab end in a newline character.  If the
+last entry in a crontab is missing a newline (i.e.\& terminated by EOF),
+cron will consider the crontab (at least partially) broken.
+A warning will be written to syslog.
+
+.SH AUTHOR
+Paul Vixie <paul@vix.com> is the author of
+.I cron
+and original creator of this manual page.  This page has also been modified for
+Debian by Steve Greenland, Javier Fernandez-Sanguino, Christian Kastner,
+Christian Pekeler, Georges Khaznadar.