Adding upstream version 4.22.0.upstream/4.22.0

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

1 files changed, 401 insertions, 0 deletions

diff --git a/upstream/archlinux/man3p/getdate.3p b/upstream/archlinux/man3p/getdate.3p
new file mode 100644
index 00000000..ce2bdcf9
--- /dev/null
+++ b/upstream/archlinux/man3p/getdate.3p
@@ -0,0 +1,401 @@
+'\" et
+.TH GETDATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+getdate
+\(em convert user format date and time
+.SH SYNOPSIS
+.LP
+.nf
+#include <time.h>
+.P
+struct tm *getdate(const char *\fIstring\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIgetdate\fR()
+function shall convert a string representation of a date or time
+into a broken-down time.
+.P
+The external variable or macro
+.IR getdate_err ,
+which has type
+.BR int ,
+is used by
+\fIgetdate\fR()
+to return error values. It is unspecified whether
+.IR getdate_err
+is a macro or an identifier declared with external linkage, and whether
+or not it is a modifiable lvalue. If a macro definition is suppressed
+in order to access an actual object, or a program defines an identifier
+with the name
+.IR getdate_err ,
+the behavior is undefined.
+.P
+Templates are used to parse and interpret the input string. The
+templates are contained in a text file identified by the environment
+variable
+.IR DATEMSK .
+The
+.IR DATEMSK
+variable should be set to indicate the full pathname of the file that
+contains the templates. The first line in the template that matches
+the input specification is used for interpretation and conversion into
+the internal time format.
+.P
+The following conversion specifications shall be supported:
+.IP "\fR%%\fR" 8
+Equivalent to
+.BR % .
+.IP "\fR%a\fR" 8
+Abbreviated weekday name.
+.IP "\fR%A\fR" 8
+Full weekday name.
+.IP "\fR%b\fR" 8
+Abbreviated month name.
+.IP "\fR%B\fR" 8
+Full month name.
+.IP "\fR%c\fR" 8
+Locale's appropriate date and time representation.
+.IP "\fR%C\fR" 8
+Century number [00,99]; leading zeros are permitted but not required.
+.IP "\fR%d\fR" 8
+Day of month [01,31]; the leading 0 is optional.
+.IP "\fR%D\fR" 8
+Date as
+.BR %m /\c
+.BR %d /\c
+.BR %y .
+.IP "\fR%e\fR" 8
+Equivalent to
+.BR %d .
+.IP "\fR%h\fR" 8
+Abbreviated month name.
+.IP "\fR%H\fR" 8
+Hour [00,23].
+.IP "\fR%I\fR" 8
+Hour [01,12].
+.IP "\fR%m\fR" 8
+Month number [01,12].
+.IP "\fR%M\fR" 8
+Minute [00,59].
+.IP "\fR%n\fR" 8
+Equivalent to
+<newline>.
+.IP "\fR%p\fR" 8
+Locale's equivalent of either AM or PM.
+.IP "\fR%r\fR" 8
+The locale's appropriate representation of time in AM and PM notation.
+In the POSIX locale, this shall be equivalent to
+.BR %I :\c
+.BR %M :\c
+.BR %S
+.BR %p .
+.IP "\fR%R\fR" 8
+Time as
+.BR %H :\c
+.BR %M .
+.IP "\fR%S\fR" 8
+Seconds [00,60]. The range goes to 60 (rather than stopping at 59)
+to allow positive leap seconds to be expressed. Since leap seconds
+cannot be predicted by any algorithm, leap second data must come from
+some external source.
+.IP "\fR%t\fR" 8
+Equivalent to
+<tab>.
+.IP "\fR%T\fR" 8
+Time as
+.BR %H :\c
+.BR %M :\c
+.BR %S .
+.IP "\fR%w\fR" 8
+Weekday number (Sunday = [0,6]).
+.IP "\fR%x\fR" 8
+Locale's appropriate date representation.
+.IP "\fR%X\fR" 8
+Locale's appropriate time representation.
+.IP "\fR%y\fR" 8
+Year within century. When a century is not otherwise specified, 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.
+.RS 8 
+.TP 10
+.BR Note:
+It is expected that in a future version of this standard the default
+century inferred from a 2-digit year will change. (This would apply
+to all commands accepting a 2-digit year as input.)
+.P
+.RE
+.IP "\fR%Y\fR" 8
+Year as
+.BR \(dqccyy\(dq 
+(for example, 2001).
+.IP "\fR%Z\fR" 8
+Timezone name or no characters if no timezone exists. If the
+timezone supplied by
+.BR %Z
+is not the timezone that
+\fIgetdate\fR()
+expects, an invalid input specification error shall result. The
+\fIgetdate\fR()
+function calculates an expected timezone based on information supplied
+to the function (such as the hour, day, and month).
+.P
+The match between the template and input specification performed by
+\fIgetdate\fR()
+shall be case-insensitive.
+.P
+The month and weekday names can consist of any combination of upper and
+lowercase letters. The process can request that the input date or time
+specification be in a specific language by setting the
+.IR LC_TIME
+category
+(see
+.IR "\fIsetlocale\fR\^(\|)").
+.P
+Leading zeros are not necessary for the descriptors that allow leading
+zeros. However, at most two digits are allowed for those descriptors,
+including leading zeros. Extra white space in either the template file
+or in
+.IR string
+shall be ignored.
+.P
+The results are undefined if the conversion specifications
+.BR %c ,
+.BR %x ,
+and
+.BR %X
+include unsupported conversion specifications.
+.P
+The following rules apply for converting the input specification into
+the internal format:
+.IP " *" 4
+If
+.BR %Z
+is being scanned, then
+\fIgetdate\fR()
+shall initialize the broken-down time to be the current time in the
+scanned timezone. Otherwise, it shall initialize the broken-down time
+based on the current local time as if
+\fIlocaltime\fR()
+had been called.
+.IP " *" 4
+If only the weekday is given, the day chosen shall be the day, starting
+with today and moving into the future, which first matches the named
+day.
+.IP " *" 4
+If only the month (and no year) is given, the month chosen shall be the
+month, starting with the current month and moving into the future,
+which first matches the named month. The first day of the month shall
+be assumed if no day is given.
+.IP " *" 4
+If no hour, minute, and second are given, the current hour, minute, and
+second shall be assumed.
+.IP " *" 4
+If no date is given, the hour chosen shall be the hour, starting with
+the current hour and moving into the future, which first matches the
+named hour.
+.P
+If a conversion specification in the DATEMSK file does not correspond
+to one of the conversion specifications above, the behavior is
+unspecified.
+.P
+The
+\fIgetdate\fR()
+function need not be thread-safe.
+.SH "RETURN VALUE"
+Upon successful completion,
+\fIgetdate\fR()
+shall return a pointer to a
+.BR "struct tm" .
+Otherwise, it shall return a null pointer and set
+.IR getdate_err
+to indicate the error.
+.SH ERRORS
+The
+\fIgetdate\fR()
+function shall fail in the following cases, setting
+.IR getdate_err
+to the value shown in the list below. Any changes to
+.IR errno
+are unspecified.
+.IP " 1." 4
+The
+.IR DATEMSK
+environment variable is null or undefined.
+.IP " 2." 4
+The template file cannot be opened for reading.
+.IP " 3." 4
+Failed to get file status information.
+.IP " 4." 4
+The template file is not a regular file.
+.IP " 5." 4
+An I/O error is encountered while reading the template file.
+.IP " 6." 4
+Memory allocation failed (not enough memory available).
+.IP " 7." 4
+There is no line in the template that matches the input.
+.IP " 8." 4
+Invalid input specification. For example, February 31; or a time is
+specified that cannot be represented in a
+.BR time_t
+(representing the time in seconds since the Epoch).
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+.IP " 1." 4
+The following example shows the possible contents of a template:
+.RS 4 
+.sp
+.RS 4
+.nf
+
+%m
+%A %B %d, %Y, %H:%M:%S
+%A
+%B
+%m/%d/%y %I %p
+%d,%m,%Y %H:%M
+at %A the %dst of %B in %Y
+run job at %I %p,%B %dnd
+%A den %d. %B %Y %H.%M Uhr
+.fi
+.P
+.RE
+.RE
+.IP " 2." 4
+The following are examples of valid input specifications for the
+template in Example 1:
+.RS 4 
+.sp
+.RS 4
+.nf
+
+getdate("10/1/87 4 PM");
+getdate("Friday");
+getdate("Friday September 18, 1987, 10:30:30");
+getdate("24,9,1986 10:30");
+getdate("at monday the 1st of december in 1986");
+getdate("run job at 3 PM, december 2nd");
+.fi
+.P
+.RE
+.P
+If the
+.IR LC_TIME
+category is set to a German locale that includes
+.IR freitag
+as a weekday name and
+.IR oktober
+as a month name, the following would be valid:
+.sp
+.RS 4
+.nf
+
+getdate("freitag den 10. oktober 1986 10.30 Uhr");
+.fi
+.P
+.RE
+.RE
+.IP " 3." 4
+The following example shows how local date and time specification can
+be defined in the template:
+.TS
+box tab(!) center;
+cB | cB
+lf5 | lf5.
+Invocation!Line in Template
+_
+getdate("11/27/86")!%m/%d/%y
+getdate("27.11.86")!%d.%m.%y
+getdate("86-11-27")!%y-%m-%d
+getdate("Friday 12:00:00")!%A %H:%M:%S
+.TE
+.IP " 4." 4
+The following examples help to illustrate the above rules assuming that
+the current date is Mon Sep 22 12:19:47 EDT 1986 and the
+.IR LC_TIME
+category is set to the default C or POSIX locale:
+.TS
+box tab(!) center;
+cB | cB | cB
+lf5 | lf5 | l.
+Input!Line in Template!Date
+_
+Mon!%a!Mon Sep 22 12:19:47 EDT 1986
+Sun!%a!Sun Sep 28 12:19:47 EDT 1986
+Fri!%a!Fri Sep 26 12:19:47 EDT 1986
+September!%B!Mon Sep 1 12:19:47 EDT 1986
+January!%B!Thu Jan 1 12:19:47 EST 1987
+December!%B!Mon Dec 1 12:19:47 EST 1986
+Sep Mon!%b %a!Mon Sep 1 12:19:47 EDT 1986
+Jan Fri!%b %a!Fri Jan 2 12:19:47 EST 1987
+Dec Mon!%b %a!Mon Dec 1 12:19:47 EST 1986
+Jan Wed 1989!%b %a %Y!Wed Jan 4 12:19:47 EST 1989
+Fri 9!%a %H!Fri Sep 26 09:00:00 EDT 1986
+Feb 10:30!%b %H:%S!Sun Feb 1 10:00:30 EST 1987
+10:30!%H:%M!Tue Sep 23 10:30:00 EDT 1986
+13:30!%H:%M!Mon Sep 22 13:30:00 EDT 1986
+.TE
+.SH "APPLICATION USAGE"
+Although historical versions of
+\fIgetdate\fR()
+did not require that
+.IR <time.h> 
+declare the external variable
+.IR getdate_err ,
+this volume of POSIX.1\(hy2017 does require it. The standard developers encourage applications
+to remove declarations of
+.IR getdate_err
+and instead incorporate the declaration by including
+.IR <time.h> .
+.P
+Applications should use
+.BR %Y
+(4-digit years) in preference to
+.BR %y
+(2-digit years).
+.SH RATIONALE
+In standard locales, the conversion specifications
+.BR %c ,
+.BR %x ,
+and
+.BR %X
+do not include unsupported conversion specifiers and so the text
+regarding results being undefined is not a problem in that case.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIctime\fR\^(\|)",
+.IR "\fIlocaltime\fR\^(\|)",
+.IR "\fIsetlocale\fR\^(\|)",
+.IR "\fIstrftime\fR\^(\|)",
+.IR "\fItimes\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<time.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 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 .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .