diff options
Diffstat (limited to 'man1p/crontab.1p')
| -rw-r--r-- | man1p/crontab.1p | 321 |
1 files changed, 321 insertions, 0 deletions
diff --git a/man1p/crontab.1p b/man1p/crontab.1p new file mode 100644 index 000000000..49353d7c6 --- /dev/null +++ b/man1p/crontab.1p @@ -0,0 +1,321 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "CRONTAB" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" crontab +.SH NAME +crontab \- schedule periodic background work +.SH SYNOPSIS +.LP +\fBcrontab\fP \fB[\fP\fIfile\fP\fB]\fP\fB +.br +.sp +crontab\fP \fB[\fP \fB-e | -l | -r\fP \fB]\fP\fB\fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIcrontab\fP utility shall create, replace, or edit a user's +crontab entry; a crontab entry is a list of commands and the +times at which they shall be executed. The new crontab entry can be +input by specifying \fIfile\fP or input from standard input if +no \fIfile\fP operand is specified, or by using an editor, if \fB-e\fP +is specified. +.LP +Upon execution of a command from a crontab entry, the implementation +shall supply a default environment, defining at least the +following environment variables: +.TP 7 +\fIHOME\fP +A pathname of the user's home directory. +.TP 7 +\fILOGNAME\fP +The user's login name. +.TP 7 +\fIPATH\fP +A string representing a search path guaranteed to find all of the +standard utilities. +.TP 7 +\fISHELL\fP +A pathname of the command interpreter. When \fIcrontab\fP is invoked +as specified by this volume of +IEEE\ Std\ 1003.1-2001, the value shall be a pathname for \fIsh\fP. +.sp +.LP +The values of these variables when \fIcrontab\fP is invoked as specified +by this volume of IEEE\ Std\ 1003.1-2001 shall +not affect the default values provided when the scheduled command +is run. +.LP +If standard output and standard error are not redirected by commands +executed from the crontab entry, any generated output or +errors shall be mailed, via an implementation-defined method, to the +user. +.LP +Users shall be permitted to use \fIcrontab\fP if their names appear +in the file \fB/usr/lib/cron/cron.allow\fP. If that file does +not exist, the file \fB/usr/lib/cron/cron.deny\fP shall be checked +to determine whether the user shall be denied access to +\fIcrontab\fP. If neither file exists, only a process with appropriate +privileges shall be allowed to submit a job. If only +\fBcron.deny\fP exists and is empty, global usage shall be permitted. +The \fBcron.allow\fP and \fBcron.deny\fP files shall +consist of one user name per line. +.SH OPTIONS +.LP +The \fIcrontab\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +.LP +The following options shall be supported: +.TP 7 +\fB-e\fP +Edit a copy of the invoking user's crontab entry, or create an empty +entry to edit if the crontab entry does not exist. When +editing is complete, the entry shall be installed as the user's crontab +entry. +.TP 7 +\fB-l\fP +(The letter ell.) List the invoking user's crontab entry. +.TP 7 +\fB-r\fP +Remove the invoking user's crontab entry. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +The pathname of a file that contains specifications, in the format +defined in the INPUT FILES section, for crontab +entries. +.sp +.SH STDIN +.LP +See the INPUT FILES section. +.SH INPUT FILES +.LP +In the POSIX locale, the user or application shall ensure that a crontab +entry is a text file consisting of lines of six fields +each. The fields shall be separated by <blank>s. The first five fields +shall be integer patterns that specify the +following: +.IP " 1." 4 +Minute [0,59] +.LP +.IP " 2." 4 +Hour [0,23] +.LP +.IP " 3." 4 +Day of the month [1,31] +.LP +.IP " 4." 4 +Month of the year [1,12] +.LP +.IP " 5." 4 +Day of the week ([0,6] with 0=Sunday) +.LP +.LP +Each of these patterns can be either an asterisk (meaning all valid +values), an element, or a list of elements separated by +commas. An element shall be either a number or two numbers separated +by a hyphen (meaning an inclusive range). The specification of +days can be made by two fields (day of the month and day of the week). +If month, day of month, and day of week are all asterisks, +every day shall be matched. If either the month or day of month is +specified as an element or list, but the day of week is an +asterisk, the month and day of month fields shall specify the days +that match. If both month and day of month are specified as an +asterisk, but day of week is an element or list, then only the specified +days of the week match. Finally, if either the month or +day of month is specified as an element or list, and the day of week +is also specified as an element or list, then any day matching +either the month and day of month, or the day of week, shall be matched. +.LP +The sixth field of a line in a crontab entry is a string that shall +be executed by \fIsh\fP +at the specified times. A percent sign character in this field shall +be translated to a <newline>. Any character preceded by +a backslash (including the \fB'%'\fP ) shall cause that character +to be treated literally. Only the first line (up to a +\fB'%'\fP or end-of-line) of the command field shall be executed by +the command interpreter. The other lines shall be made +available to the command as standard input. +.LP +Blank lines and those whose first non- <blank> is \fB'#'\fP shall +be ignored. +.LP +The text files \fB/usr/lib/cron/cron.allow\fP and \fB/usr/lib/cron/cron.deny\fP +shall contain zero or more user names, one per +line, of users who are, respectively, authorized or denied access +to the service underlying the \fIcrontab\fP utility. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIcrontab\fP: +.TP 7 +\fIEDITOR\fP +Determine the editor to be invoked when the \fB-e\fP option is specified. +The default editor shall be \fIvi\fP. +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as +opposed to multi-byte characters in arguments and input files). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +If the \fB-l\fP option is specified, the crontab entry shall be written +to the standard output. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +The user's crontab entry is not submitted, removed, edited, or listed. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +The format of the crontab entry shown here is guaranteed only for +the POSIX locale. Other cultures may be supported with +substantially different interfaces, although implementations are encouraged +to provide comparable levels of functionality. +.LP +The default settings of the \fIHOME ,\fP \fILOGNAME ,\fP \fIPATH ,\fP +and \fISHELL\fP variables that are given to the +scheduled job are not affected by the settings of those variables +when \fIcrontab\fP is run; as stated, they are defaults. The +text about "invoked as specified by this volume of IEEE\ Std\ 1003.1-2001" +means that the implementation may provide +extensions that allow these variables to be affected at runtime, but +that the user has to take explicit action in order to access +the extension, such as give a new option flag or modify the format +of the crontab entry. +.LP +A typical user error is to type only \fIcrontab\fP; this causes the +system to wait for the new crontab entry on standard input. +If end-of-file is typed (generally <control>-D), the crontab entry +is replaced by an empty file. In this case, the user +should type the interrupt character, which prevents the crontab entry +from being replaced. +.SH EXAMPLES +.IP " 1." 4 +Clean up \fBcore\fP files every weekday morning at 3:15 am: +.sp +.RS +.nf + +\fB15 3 * * 1-5 find $HOME -name core 2>/dev/null | xargs rm -f +\fP +.fi +.RE +.LP +.IP " 2." 4 +Mail a birthday greeting: +.sp +.RS +.nf + +\fB0 12 14 2 * mailx john%Happy Birthday!%Time for lunch. +\fP +.fi +.RE +.LP +.IP " 3." 4 +As an example of specifying the two types of days: +.sp +.RS +.nf + +\fB0 0 1,15 * 1 +\fP +.fi +.RE +.LP +would run a command on the first and fifteenth of each month, as well +as on every Monday. To specify days by only one field, the +other field should be set to \fB'*'\fP ; for example: +.sp +.RS +.nf + +\fB0 0 * * 1 +\fP +.fi +.RE +.LP +would run a command only on Mondays. +.LP +.SH RATIONALE +.LP +All references to a \fIcron\fP daemon and to \fIcron\fP \fIfiles\fP +have been omitted. Although historical implementations +have used this arrangement, there is no reason to limit future implementations. +.LP +This description of \fIcrontab\fP is designed to support only users +with normal privileges. The format of the input is based on +the System V \fIcrontab\fP; however, there is no requirement here +that the actual system database used by the \fIcron\fP daemon +(or a similar mechanism) use this format internally. For example, +systems derived from BSD are likely to have an additional field +appended that indicates the user identity to be used when the job +is submitted. +.LP +The \fB-e\fP option was adopted from the SVID as a user convenience, +although it does not exist in all historical +implementations. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIat\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |