1 files changed, 572 insertions, 0 deletions
diff --git a/man1p/date.1p b/man1p/date.1p
new file mode 100644
index 000000000..0fa9828a5
--- /dev/null
+++ b/man1p/date.1p
@@ -0,0 +1,572 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "DATE" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" date 
+.SH NAME
+date \- write the date and time
+.SH SYNOPSIS
+.LP
+\fBdate\fP \fB[\fP\fB-u\fP\fB] [\fP\fB+\fP\fIformat\fP\fB]\fP\fB
+.br
+.sp
+\fP
+.LP
+\fBdate\fP \fB[\fP\fB-u\fP\fB]\fP
+\fImmddhhmm\fP\fB[[\fP\fIcc\fP\fB]\fP\fIyy\fP\fB]\fP\fB\fP
+\fB
+.br
+\fP
+.SH DESCRIPTION
+.LP
+The \fIdate\fP utility shall write the date and time to standard output
+\ or attempt
+to set the system date and time.  By default, the current date and
+time shall be written. If an operand beginning with \fB'+'\fP is specified,
+the output format of \fIdate\fP shall be controlled
+by the conversion specifications and other text in the operand.
+.SH OPTIONS
+.LP
+The \fIdate\fP utility shall conform to the Base Definitions volume
+of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
+.LP
+The following option shall be supported:
+.TP 7
+\fB-u\fP
+Perform operations as if the \fITZ\fP environment variable was set
+to the string \fB"UTC0"\fP , or its equivalent
+historical value of \fB"GMT0"\fP . Otherwise, \fIdate\fP shall use
+the timezone indicated by the \fITZ\fP environment variable
+or the system default if that variable is unset or null.
+.sp
+.SH OPERANDS
+.LP
+The following operands shall be supported:
+.TP 7
++\fIformat\fP
+When the format is specified, each conversion specifier shall be replaced
+in the standard output by its corresponding value.
+All other characters shall be copied to the output without change.
+The output shall always be terminated with a
+<newline>.
+.sp
+.SS Conversion Specifications
+.TP 7
+\fB%a\fP
+Locale's abbreviated weekday name.
+.TP 7
+\fB%A\fP
+Locale's full weekday name.
+.TP 7
+\fB%b\fP
+Locale's abbreviated month name.
+.TP 7
+\fB%B\fP
+Locale's full month name.
+.TP 7
+\fB%c\fP
+Locale's appropriate date and time representation.
+.TP 7
+\fB%C\fP
+Century (a year divided by 100 and truncated to an integer) as a decimal
+number [00,99].
+.TP 7
+\fB%d\fP
+Day of the month as a decimal number [01,31].
+.TP 7
+\fB%D\fP
+Date in the format \fImm\fP/\fIdd\fP/\fIyy\fP.
+.TP 7
+\fB%e\fP
+Day of the month as a decimal number [1,31] in a two-digit field with
+leading space character fill.
+.TP 7
+\fB%h\fP
+A synonym for \fB%b\fP .
+.TP 7
+\fB%H\fP
+Hour (24-hour clock) as a decimal number [00,23].
+.TP 7
+\fB%I\fP
+Hour (12-hour clock) as a decimal number [01,12].
+.TP 7
+\fB%j\fP
+Day of the year as a decimal number [001,366].
+.TP 7
+\fB%m\fP
+Month as a decimal number [01,12].
+.TP 7
+\fB%M\fP
+Minute as a decimal number [00,59].
+.TP 7
+\fB%n\fP
+A <newline>.
+.TP 7
+\fB%p\fP
+Locale's equivalent of either AM or PM.
+.TP 7
+\fB%r\fP
+12-hour clock time [01,12] using the AM/PM notation; in the POSIX
+locale, this shall be equivalent to \fB%I\fP : \fB%M\fP
+: \fB%S\fP \fB%p\fP .
+.TP 7
+\fB%S\fP
+Seconds as a decimal number [00,60].
+.TP 7
+\fB%t\fP
+A <tab>.
+.TP 7
+\fB%T\fP
+24-hour clock time [00,23] in the format \fIHH\fP:\fIMM\fP:\fISS\fP.
+.TP 7
+\fB%u\fP
+Weekday as a decimal number [1,7] (1=Monday).
+.TP 7
+\fB%U\fP
+Week of the year (Sunday as the first day of the week) as a decimal
+number [00,53]. All days in a new year preceding the first
+Sunday shall be considered to be in week 0.
+.TP 7
+\fB%V\fP
+Week of the year (Monday as the first day of the week) as a decimal
+number [01,53]. If the week containing January 1 has four
+or more days in the new year, then it shall be considered week 1;
+otherwise, it shall be the last week of the previous year, and
+the next week shall be week 1.
+.TP 7
+\fB%w\fP
+Weekday as a decimal number [0,6] (0=Sunday).
+.TP 7
+\fB%W\fP
+Week of the year (Monday as the first day of the week) as a decimal
+number [00,53]. All days in a new year preceding the first
+Monday shall be considered to be in week 0.
+.TP 7
+\fB%x\fP
+Locale's appropriate date representation.
+.TP 7
+\fB%X\fP
+Locale's appropriate time representation.
+.TP 7
+\fB%y\fP
+Year within century [00,99].
+.TP 7
+\fB%Y\fP
+Year with century as a decimal number.
+.TP 7
+\fB%Z\fP
+Timezone name, or no characters if no timezone is determinable.
+.TP 7
+\fB%%\fP
+A percent sign character.
+.sp
+.LP
+See the Base Definitions volume of IEEE\ Std\ 1003.1-2001, Section
+7.3.5, LC_TIME for the conversion specifier values in the POSIX locale.
+.SS Modified Conversion Specifications
+.LP
+Some conversion specifiers can be modified by the \fBE\fP and \fBO\fP
+modifier characters to indicate a different format
+or specification as specified in the \fILC_TIME\fP locale description
+(see the Base Definitions volume of
+IEEE\ Std\ 1003.1-2001, Section 7.3.5, LC_TIME). If the
+corresponding keyword (see \fBera\fP, \fBera_year\fP, \fBera_d_fmt\fP,
+and \fBalt_digits\fP in the Base Definitions volume of
+IEEE\ Std\ 1003.1-2001, Section 7.3.5, LC_TIME) is not specified or
+not supported for the current locale, the unmodified conversion specifier
+value shall be used.
+.TP 7
+\fB%Ec\fP
+Locale's alternative appropriate date and time representation.
+.TP 7
+\fB%EC\fP
+The name of the base year (period) in the locale's alternative representation.
+.TP 7
+\fB%Ex\fP
+Locale's alternative date representation.
+.TP 7
+\fB%EX\fP
+Locale's alternative time representation.
+.TP 7
+\fB%Ey\fP
+Offset from \fB%EC\fP (year only) in the locale's alternative representation.
+.TP 7
+\fB%EY\fP
+Full alternative year representation.
+.TP 7
+\fB%Od\fP
+Day of month using the locale's alternative numeric symbols.
+.TP 7
+\fB%Oe\fP
+Day of month using the locale's alternative numeric symbols.
+.TP 7
+\fB%OH\fP
+Hour (24-hour clock) using the locale's alternative numeric symbols.
+.TP 7
+\fB%OI\fP
+Hour (12-hour clock) using the locale's alternative numeric symbols.
+.TP 7
+\fB%Om\fP
+Month using the locale's alternative numeric symbols.
+.TP 7
+\fB%OM\fP
+Minutes using the locale's alternative numeric symbols.
+.TP 7
+\fB%OS\fP
+Seconds using the locale's alternative numeric symbols.
+.TP 7
+\fB%Ou\fP
+Weekday as a number in the locale's alternative representation (Monday
+= 1).
+.TP 7
+\fB%OU\fP
+Week number of the year (Sunday as the first day of the week) using
+the locale's alternative numeric symbols.
+.TP 7
+\fB%OV\fP
+Week number of the year (Monday as the first day of the week, rules
+corresponding to \fB%V\fP ), using the locale's
+alternative numeric symbols.
+.TP 7
+\fB%Ow\fP
+Weekday as a number in the locale's alternative representation (Sunday
+= 0).
+.TP 7
+\fB%OW\fP
+Week number of the year (Monday as the first day of the week) using
+the locale's alternative numeric symbols.
+.TP 7
+\fB%Oy\fP
+Year (offset from \fB%C\fP ) in alternative representation.
+.sp
+.sp
+.TP 7
+\fImmddhhmm\fP\fB[[\fP\fIcc\fP\fB]\fP\fIyy\fP\fB]\fP
+.sp
+Attempt to set the system date and time from the value given in the
+operand. This is only possible if the user has appropriate
+privileges and the system permits the setting of the system date and
+time. The first \fImm\fP is the month (number); \fIdd\fP is
+the day (number); \fIhh\fP is the hour (number, 24-hour system); the
+second \fImm\fP is the minute (number); \fIcc\fP is the
+century and is the first two digits of the year (this is optional);
+\fIyy\fP is the last two digits of the year and is optional.
+If century is not specified, then values in the range [69,99] shall
+refer to years 1969 to 1999 inclusive, and values in the range
+[00,68] shall refer to years 2000 to 2068 inclusive. The current year
+is the default if \fIyy\fP is omitted.   
+.TP 7
+\fBNote:\fP
+.RS
+It is expected that in a future version of IEEE\ Std\ 1003.1-2001
+the default century inferred from a 2-digit year will
+change. (This would apply to all commands accepting a 2-digit year
+as input.)
+.RE
+.sp
+.sp
+.SH STDIN
+.LP
+Not used.
+.SH INPUT FILES
+.LP
+None.
+.SH ENVIRONMENT VARIABLES
+.LP
+The following environment variables shall affect the execution of
+\fIdate\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).
+.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
+\fILC_TIME\fP
+Determine the format and contents of date and time strings written
+by \fIdate\fP.
+.TP 7
+\fINLSPATH\fP
+Determine the location of message catalogs for the processing of \fILC_MESSAGES
+\&.\fP 
+.TP 7
+\fITZ\fP
+Determine the timezone in which the time and date are written, unless
+the \fB-u\fP option is specified. If the \fITZ\fP
+variable is unset or null and \fB-u\fP is not specified, an unspecified
+system default timezone is used.
+.sp
+.SH ASYNCHRONOUS EVENTS
+.LP
+Default.
+.SH STDOUT
+.LP
+When no formatting operand is specified, the output in the POSIX locale
+shall be equivalent to specifying:
+.sp
+.RS
+.nf
+
+\fBdate "+%a %b %e %H:%M:%S %Z %Y"
+\fP
+.fi
+.RE
+.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
+The date was written successfully.
+.TP 7
+>0
+An error occurred.
+.sp
+.SH CONSEQUENCES OF ERRORS
+.LP
+Default.
+.LP
+\fIThe following sections are informative.\fP
+.SH APPLICATION USAGE
+.LP
+Conversion specifiers are of unspecified format when not in the POSIX
+locale. Some of them can contain <newline>s in some
+locales, so it may be difficult to use the format shown in standard
+output for parsing the output of \fIdate\fP in those
+locales.
+.LP
+The range of values for \fB%S\fP extends from 0 to 60 seconds to accommodate
+the occasional leap second.
+.LP
+Although certain of the conversion specifiers in the POSIX locale
+(such as the name of the month) are shown with initial capital
+letters, this need not be the case in other locales. Programs using
+these fields may need to adjust the capitalization if the
+output is going to be used at the beginning of a sentence.
+.LP
+The date string formatting capabilities are intended for use in Gregorian-style
+calendars, possibly with a different starting
+year (or years). The \fB%x\fP and \fB%c\fP conversion specifications,
+however, are intended for local representation; these
+may be based on a different, non-Gregorian calendar.
+.LP
+The \fB%C\fP conversion specification was introduced to allow a fallback
+for the \fB%EC\fP (alternative year format base
+year); it can be viewed as the base of the current subdivision in
+the Gregorian calendar. The century number is calculated as the
+year divided by 100 and truncated to an integer; it should not be
+confused with the use of ordinal numbers for centuries (for
+example, "twenty-first century".) Both the \fB%Ey\fP and \fB%y\fP
+can then be viewed as the offset from \fB%EC\fP and
+\fB%C\fP , respectively.
+.LP
+The \fBE\fP and \fBO\fP modifiers modify the traditional conversion
+specifiers, so that they can always be used, even if
+the implementation (or the current locale) does not support the modifier.
+.LP
+The \fBE\fP modifier supports alternative date formats, such as the
+Japanese Emperor's Era, as long as these are based on the
+Gregorian calendar system. Extending the \fBE\fP modifiers to other
+date elements may provide an implementation-defined
+extension capable of supporting other calendar systems, especially
+in combination with the \fBO\fP modifier.
+.LP
+The \fBO\fP modifier supports time and date formats using the locale's
+alternative numerical symbols, such as Kanji or Hindi
+digits or ordinal number representation.
+.LP
+Non-European locales, whether they use Latin digits in computational
+items or not, often have local forms of the digits for use
+in date formats. This is not totally unknown even in Europe; a variant
+of dates uses Roman numerals for the months: the third day
+of September 1991 would be written as 3.IX.1991. In Japan, Kanji digits
+are regularly used for dates; in Arabic-speaking countries,
+Hindi digits are used. The \fB%d\fP , \fB%e\fP , \fB%H\fP , \fB%I\fP
+, \fB%m\fP , \fB%S\fP , \fB%U\fP ,
+\fB%w\fP , \fB%W\fP , and \fB%y\fP conversion specifications always
+return the date and time field in Latin digits (that
+is, 0 to 9). The \fB%O\fP modifier was introduced to support the use
+for display purposes of non-Latin digits. In the
+\fILC_TIME\fP category in \fIlocaledef\fP, the optional \fBalt_digits\fP
+keyword is
+intended for this purpose. As an example, assume the following (partial)
+\fIlocaledef\fP
+source:
+.sp
+.RS
+.nf
+
+\fBalt_digits  "";"I";"II";"III";"IV";"V";"VI";"VII";"VIII" \\
+            "IX";"X";"XI";"XII"
+d_fmt       "%e.%Om.%Y"
+\fP
+.fi
+.RE
+.LP
+With the above date, the command:
+.sp
+.RS
+.nf
+
+\fBdate "+%x"
+\fP
+.fi
+.RE
+.LP
+would yield 3.IX.1991. With the same \fBd_fmt\fP, but without the
+\fBalt_digits\fP, the command would yield 3.9.1991.
+.SH EXAMPLES
+.IP " 1." 4
+The following are input/output examples of \fIdate\fP used at arbitrary
+times in the POSIX locale:
+.sp
+.RS
+.nf
+
+\fB$\fP \fBdate
+\fP\fBTue Jun 26 09:58:10 PDT 1990
+.sp
+
+$\fP \fBdate "+DATE: %m/%d/%y%nTIME: %H:%M:%S"
+\fP\fBDATE: 11/02/91
+TIME: 13:36:16
+.sp
+
+$\fP \fBdate "+TIME: %r"
+\fP\fBTIME: 01:36:32 PM\fP
+.fi
+.RE
+.LP
+.IP " 2." 4
+Examples for Denmark, where the default date and time format is \fB%a\fP
+\fB%d\fP \fB%b\fP \fB%Y\fP \fB%T\fP
+\fB%Z\fP :
+.sp
+.RS
+.nf
+
+\fB$\fP \fBLANG=da_DK.iso_8859-1 date
+\fP\fBons 02 okt 1991 15:03:32 CET
+.sp
+
+$\fP \fBLANG=da_DK.iso_8859-1 \\
+    date "+DATO: %A den %e. %B %Y%nKLOKKEN: %H:%M:%S"
+\fP\fBDATO: onsdag den 2. oktober 1991
+KLOKKEN: 15:03:56\fP
+.fi
+.RE
+.LP
+.IP " 3." 4
+Examples for Germany, where the default date and time format is \fB%a\fP
+\fB%d\fP . \fB%h\fP . \fB%Y\fP ,
+\fB%T\fP \fB%Z\fP :
+.sp
+.RS
+.nf
+
+\fB$\fP \fBLANG=De_DE.88591 date
+\fP\fBMi 02.Okt.1991, 15:01:21 MEZ
+.sp
+
+$\fP \fBLANG=De_DE.88591 date "+DATUM: %A, %d. %B %Y%nZEIT: %H:%M:%S"
+\fP\fBDATUM: Mittwoch, 02. Oktober 1991
+ZEIT: 15:02:02\fP
+.fi
+.RE
+.LP
+.IP " 4." 4
+Examples for France, where the default date and time format is \fB%a\fP
+\fB%d\fP \fB%h\fP \fB%Y\fP \fB%Z\fP
+\fB%T\fP :
+.sp
+.RS
+.nf
+
+\fB$\fP \fBLANG=Fr_FR.88591 date
+\fP\fBMer 02 oct 1991 MET 15:03:32
+.sp
+
+$\fP \fBLANG=Fr_FR.88591 date "+JOUR: %A %d %B %Y%nHEURE: %H:%M:%S"
+\fP\fBJOUR: Mercredi 02 octobre 1991
+HEURE: 15:03:56\fP
+.fi
+.RE
+.LP
+.SH RATIONALE
+.LP
+Some of the new options for formatting are from the ISO\ C standard.
+The \fB-u\fP option was introduced to allow portable
+access to Coordinated Universal Time (UTC). The string \fB"GMT0"\fP
+is allowed as an equivalent \fITZ\fP value to be compatible
+with all of the systems using the BSD implementation, where this option
+originated.
+.LP
+The \fB%e\fP format conversion specification (adopted from System
+V) was added because the ISO\ C standard conversion
+specifications did not provide any way to produce the historical default
+\fIdate\fP output during the first nine days of any
+month.
+.LP
+There are two varieties of day and week numbering supported (in addition
+to any others created with the locale-dependent
+\fB%E\fP and \fB%O\fP modifier characters):
+.IP " *" 3
+The historical variety in which Sunday is the first day of the week
+and the weekdays preceding the first Sunday of the year are
+considered week 0. These are represented by \fB%w\fP and \fB%U\fP
+\&. A variant of this is \fB%W\fP , using Monday as the
+first day of the week, but still referring to week 0. This view of
+the calendar was retained because so many historical
+applications depend on it and the ISO\ C standard \fIstrftime\fP()
+function, on which
+many \fIdate\fP implementations are based, was defined in this way.
+.LP
+.IP " *" 3
+The international standard, based on the ISO\ 8601:2000 standard where
+Monday is the first weekday and the algorithm for the
+first week number is more complex: If the week (Monday to Sunday)
+containing January 1 has four or more days in the new year, then
+it is week 1; otherwise, it is week 53 of the previous year, and the
+next week is week 1. These are represented by the new
+conversion specifications \fB%u\fP and \fB%V\fP , added as a result
+of international comments.
+.LP
+.SH FUTURE DIRECTIONS
+.LP
+None.
+.SH SEE ALSO
+.LP
+The System Interfaces volume of IEEE\ Std\ 1003.1-2001, \fIprintf\fP(),
+\fIstrftime\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 .