|
Packit |
7cfc04 |
'\" et
|
|
Packit |
7cfc04 |
.TH ASCTIME "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH PROLOG
|
|
Packit |
7cfc04 |
This manual page is part of the POSIX Programmer's Manual.
|
|
Packit |
7cfc04 |
The Linux implementation of this interface may differ (consult
|
|
Packit |
7cfc04 |
the corresponding Linux manual page for details of Linux behavior),
|
|
Packit |
7cfc04 |
or the interface may not be implemented on Linux.
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
asctime,
|
|
Packit |
7cfc04 |
asctime_r
|
|
Packit |
7cfc04 |
\(em convert date and time to a string
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
#include <time.h>
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
char *asctime(const struct tm *\fItimeptr\fP);
|
|
Packit |
7cfc04 |
char *asctime_r(const struct tm *restrict \fItm\fP, char *restrict \fIbuf\fP);
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
For
|
|
Packit |
7cfc04 |
\fIasctime\fR():
|
|
Packit |
7cfc04 |
The functionality described on this reference page is aligned with the
|
|
Packit |
7cfc04 |
ISO\ C standard. Any conflict between the requirements described here and the
|
|
Packit |
7cfc04 |
ISO\ C standard is unintentional. This volume of POSIX.1\(hy2008 defers to the ISO\ C standard.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIasctime\fR()
|
|
Packit |
7cfc04 |
function shall convert the broken-down time in the structure pointed
|
|
Packit |
7cfc04 |
to by
|
|
Packit |
7cfc04 |
.IR timeptr
|
|
Packit |
7cfc04 |
into a string in the form:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
Sun Sep 16 01:03:52 1973\en\e0
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
using the equivalent of the following algorithm:
|
|
Packit |
7cfc04 |
.sp
|
|
Packit |
7cfc04 |
.RS 4
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
\fB
|
|
Packit |
7cfc04 |
char *asctime(const struct tm *timeptr)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
static char wday_name[7][3] = {
|
|
Packit |
7cfc04 |
"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
static char mon_name[12][3] = {
|
|
Packit |
7cfc04 |
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
|
|
Packit |
7cfc04 |
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
static char result[26];
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\en",
|
|
Packit |
7cfc04 |
wday_name[timeptr->tm_wday],
|
|
Packit |
7cfc04 |
mon_name[timeptr->tm_mon],
|
|
Packit |
7cfc04 |
timeptr->tm_mday, timeptr->tm_hour,
|
|
Packit |
7cfc04 |
timeptr->tm_min, timeptr->tm_sec,
|
|
Packit |
7cfc04 |
1900 + timeptr->tm_year);
|
|
Packit |
7cfc04 |
return result;
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.fi \fR
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
However, the behavior is undefined if \fItimeptr\fR\->\fItm_wday\fR or
|
|
Packit |
7cfc04 |
\fItimeptr\fR\->\fItm_mon\fR are not within the normal ranges as
|
|
Packit |
7cfc04 |
defined in
|
|
Packit |
7cfc04 |
.IR <time.h> ,
|
|
Packit |
7cfc04 |
or if \fItimeptr\fR\->\fItm_year\fR exceeds
|
|
Packit |
7cfc04 |
{INT_MAX}\(mi1990,
|
|
Packit |
7cfc04 |
or if the above algorithm would attempt to generate more than 26 bytes
|
|
Packit |
7cfc04 |
of output (including the terminating null).
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR tm
|
|
Packit |
7cfc04 |
structure is defined in the
|
|
Packit |
7cfc04 |
.IR <time.h>
|
|
Packit |
7cfc04 |
header.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIasctime\fR(),
|
|
Packit |
7cfc04 |
\fIctime\fR(),
|
|
Packit |
7cfc04 |
\fIgmtime\fR(),
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIlocaltime\fR()
|
|
Packit |
7cfc04 |
functions shall return values in one of two static objects: a
|
|
Packit |
7cfc04 |
broken-down time structure and an array of type
|
|
Packit |
7cfc04 |
.BR char .
|
|
Packit |
7cfc04 |
Execution of any of the functions may overwrite the information
|
|
Packit |
7cfc04 |
returned in either of these objects by any of the other functions.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIasctime\fR()
|
|
Packit |
7cfc04 |
function need not be thread-safe.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIasctime_r\fR()
|
|
Packit |
7cfc04 |
function shall convert the broken-down time in the structure pointed to
|
|
Packit |
7cfc04 |
by
|
|
Packit |
7cfc04 |
.IR tm
|
|
Packit |
7cfc04 |
into a string (of the same form as that returned by
|
|
Packit |
7cfc04 |
\fIasctime\fR(),
|
|
Packit |
7cfc04 |
and with the same undefined behavior when input or output is out of
|
|
Packit |
7cfc04 |
range) that is placed in the user-supplied buffer pointed to by
|
|
Packit |
7cfc04 |
.IR buf
|
|
Packit |
7cfc04 |
(which shall contain at least 26 bytes) and then return
|
|
Packit |
7cfc04 |
.IR buf .
|
|
Packit |
7cfc04 |
.SH "RETURN VALUE"
|
|
Packit |
7cfc04 |
Upon successful completion,
|
|
Packit |
7cfc04 |
\fIasctime\fR()
|
|
Packit |
7cfc04 |
shall return a pointer to the string.
|
|
Packit |
7cfc04 |
If the function is unsuccessful, it shall return NULL.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Upon successful completion,
|
|
Packit |
7cfc04 |
\fIasctime_r\fR()
|
|
Packit |
7cfc04 |
shall return a pointer to a character string containing the date and
|
|
Packit |
7cfc04 |
time. This string is pointed to by the argument
|
|
Packit |
7cfc04 |
.IR buf .
|
|
Packit |
7cfc04 |
If the function is unsuccessful, it shall return NULL.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
No errors are defined.
|
|
Packit |
7cfc04 |
.LP
|
|
Packit |
7cfc04 |
.IR "The following sections are informative."
|
|
Packit |
7cfc04 |
.SH EXAMPLES
|
|
Packit |
7cfc04 |
None.
|
|
Packit |
7cfc04 |
.SH "APPLICATION USAGE"
|
|
Packit |
7cfc04 |
These functions are included only for compatibility with older
|
|
Packit |
7cfc04 |
implementations. They have undefined behavior if the resulting string
|
|
Packit |
7cfc04 |
would be too long, so the use of these functions should be
|
|
Packit |
7cfc04 |
discouraged. On implementations that do not detect output string
|
|
Packit |
7cfc04 |
length overflow, it is possible to overflow the output buffers in such
|
|
Packit |
7cfc04 |
a way as to cause applications to fail, or possible system security
|
|
Packit |
7cfc04 |
violations. Also, these functions do not support localized date and
|
|
Packit |
7cfc04 |
time formats. To avoid these problems, applications should use
|
|
Packit |
7cfc04 |
\fIstrftime\fR()
|
|
Packit |
7cfc04 |
to generate strings from broken-down times.
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
Values for the broken-down time structure can be obtained by calling
|
|
Packit |
7cfc04 |
\fIgmtime\fR()
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
\fIlocaltime\fR().
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
\fIasctime_r\fR()
|
|
Packit |
7cfc04 |
function is thread-safe and shall return values in a user-supplied
|
|
Packit |
7cfc04 |
buffer instead of possibly using a static data area that may be
|
|
Packit |
7cfc04 |
overwritten by each call.
|
|
Packit |
7cfc04 |
.SH RATIONALE
|
|
Packit |
7cfc04 |
The standard developers decided to mark the
|
|
Packit |
7cfc04 |
\fIasctime\fR()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
\fIasctime_r\fR()
|
|
Packit |
7cfc04 |
functions obsolescent even though
|
|
Packit |
7cfc04 |
\fIasctime\fR()
|
|
Packit |
7cfc04 |
is in the ISO\ C standard due to the possibility of buffer overflow. The ISO\ C standard
|
|
Packit |
7cfc04 |
also provides the
|
|
Packit |
7cfc04 |
\fIstrftime\fR()
|
|
Packit |
7cfc04 |
function which can be used to avoid these problems.
|
|
Packit |
7cfc04 |
.SH "FUTURE DIRECTIONS"
|
|
Packit |
7cfc04 |
These functions may be removed in a future version.
|
|
Packit |
7cfc04 |
.SH "SEE ALSO"
|
|
Packit |
7cfc04 |
.IR "\fIclock\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIctime\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIdifftime\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIgmtime\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIlocaltime\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fImktime\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIstrftime\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIstrptime\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fItime\fR\^(\|)",
|
|
Packit |
7cfc04 |
.IR "\fIutime\fR\^(\|)"
|
|
Packit |
7cfc04 |
.P
|
|
Packit |
7cfc04 |
The Base Definitions volume of POSIX.1\(hy2008,
|
|
Packit |
7cfc04 |
.IR "\fB<time.h>\fP"
|
|
Packit |
7cfc04 |
.SH COPYRIGHT
|
|
Packit |
7cfc04 |
Portions of this text are reprinted and reproduced in electronic form
|
|
Packit |
7cfc04 |
from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
|
|
Packit |
7cfc04 |
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Packit |
7cfc04 |
Specifications Issue 7, Copyright (C) 2013 by the Institute of
|
|
Packit |
7cfc04 |
Electrical and Electronics Engineers, Inc and The Open Group.
|
|
Packit |
7cfc04 |
(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
|
|
Packit |
7cfc04 |
event of any discrepancy between this version and the original IEEE and
|
|
Packit |
7cfc04 |
The Open Group Standard, the original IEEE and The Open Group Standard
|
|
Packit |
7cfc04 |
is the referee document. The original Standard can be obtained online at
|
|
Packit |
7cfc04 |
http://www.unix.org/online.html .
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
Any typographical or formatting errors that appear
|
|
Packit |
7cfc04 |
in this page are most likely
|
|
Packit |
7cfc04 |
to have been introduced during the conversion of the source files to
|
|
Packit |
7cfc04 |
man page format. To report such errors, see
|
|
Packit |
7cfc04 |
https://www.kernel.org/doc/man-pages/reporting_bugs.html .
|