diff options
Diffstat (limited to 'upstream/archlinux/man3p/asctime.3p')
| -rw-r--r-- | upstream/archlinux/man3p/asctime.3p | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/asctime.3p b/upstream/archlinux/man3p/asctime.3p new file mode 100644 index 00000000..5e930122 --- /dev/null +++ b/upstream/archlinux/man3p/asctime.3p @@ -0,0 +1,199 @@ +'\" et +.TH ASCTIME "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 +asctime, +asctime_r +\(em convert date and time to a string +.SH SYNOPSIS +.LP +.nf +#include <time.h> +.P +char *asctime(const struct tm *\fItimeptr\fP); +char *asctime_r(const struct tm *restrict \fItm\fP, char *restrict \fIbuf\fP); +.fi +.SH DESCRIPTION +For +\fIasctime\fR(): +The functionality described on this reference page is aligned with the +ISO\ C standard. Any conflict between the requirements described here and the +ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard. +.P +The +\fIasctime\fR() +function shall convert the broken-down time in the structure pointed +to by +.IR timeptr +into a string in the form: +.sp +.RS 4 +.nf + +Sun Sep 16 01:03:52 1973\en\e0 +.fi +.P +.RE +.P +using the equivalent of the following algorithm: +.sp +.RS 4 +.nf + +char *asctime(const struct tm *timeptr) +{ + static char wday_name[7][3] = { + "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" + }; + static char mon_name[12][3] = { + "Jan", "Feb", "Mar", "Apr", "May", "Jun", + "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" + }; + static char result[26]; +.P + sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\en", + wday_name[timeptr->tm_wday], + mon_name[timeptr->tm_mon], + timeptr->tm_mday, timeptr->tm_hour, + timeptr->tm_min, timeptr->tm_sec, + 1900 + timeptr->tm_year); + return result; +} +.fi +.P +.RE +.P +However, the behavior is undefined if \fItimeptr\fR\->\fItm_wday\fR or +\fItimeptr\fR\->\fItm_mon\fR are not within the normal ranges as +defined in +.IR <time.h> , +or if \fItimeptr\fR\->\fItm_year\fR exceeds +{INT_MAX}\-1990, +or if the above algorithm would attempt to generate more than 26 bytes +of output (including the terminating null). +.P +The +.BR tm +structure is defined in the +.IR <time.h> +header. +.P +The +\fIasctime\fR(), +\fIctime\fR(), +\fIgmtime\fR(), +and +\fIlocaltime\fR() +functions shall return values in one of two static objects: a +broken-down time structure and an array of type +.BR char . +Execution of any of the functions may overwrite the information +returned in either of these objects by any of the other functions. +.P +The +\fIasctime\fR() +function need not be thread-safe. +.P +The +\fIasctime_r\fR() +function shall convert the broken-down time in the structure pointed to +by +.IR tm +into a string (of the same form as that returned by +\fIasctime\fR(), +and with the same undefined behavior when input or output is out of +range) that is placed in the user-supplied buffer pointed to by +.IR buf +(which shall contain at least 26 bytes) and then return +.IR buf . +.SH "RETURN VALUE" +Upon successful completion, +\fIasctime\fR() +shall return a pointer to the string. +If the function is unsuccessful, it shall return NULL. +.P +Upon successful completion, +\fIasctime_r\fR() +shall return a pointer to a character string containing the date and +time. This string is pointed to by the argument +.IR buf . +If the function is unsuccessful, it shall return NULL. +.SH ERRORS +No errors are defined. +.LP +.IR "The following sections are informative." +.SH EXAMPLES +None. +.SH "APPLICATION USAGE" +These functions are included only for compatibility with older +implementations. They have undefined behavior if the resulting string +would be too long, so the use of these functions should be +discouraged. On implementations that do not detect output string +length overflow, it is possible to overflow the output buffers in such +a way as to cause applications to fail, or possible system security +violations. Also, these functions do not support localized date and +time formats. To avoid these problems, applications should use +\fIstrftime\fR() +to generate strings from broken-down times. +.P +Values for the broken-down time structure can be obtained by calling +\fIgmtime\fR() +or +\fIlocaltime\fR(). +.P +The +\fIasctime_r\fR() +function is thread-safe and shall return values in a user-supplied +buffer instead of possibly using a static data area that may be +overwritten by each call. +.SH RATIONALE +The standard developers decided to mark the +\fIasctime\fR() +and +\fIasctime_r\fR() +functions obsolescent even though +\fIasctime\fR() +is in the ISO\ C standard due to the possibility of buffer overflow. The ISO\ C standard +also provides the +\fIstrftime\fR() +function which can be used to avoid these problems. +.SH "FUTURE DIRECTIONS" +These functions may be removed in a future version. +.SH "SEE ALSO" +.IR "\fIclock\fR\^(\|)", +.IR "\fIctime\fR\^(\|)", +.IR "\fIdifftime\fR\^(\|)", +.IR "\fIgmtime\fR\^(\|)", +.IR "\fIlocaltime\fR\^(\|)", +.IR "\fImktime\fR\^(\|)", +.IR "\fIstrftime\fR\^(\|)", +.IR "\fIstrptime\fR\^(\|)", +.IR "\fItime\fR\^(\|)", +.IR "\fIutime\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 . |