mirror of https://github.com/mkerrisk/man-pages
141 lines
4.2 KiB
Plaintext
141 lines
4.2 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "ASCTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" asctime
|
||
|
.SH NAME
|
||
|
asctime, asctime_r \- convert date and time to a string
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <time.h>
|
||
|
.br
|
||
|
.sp
|
||
|
char *asctime(const struct tm *\fP\fItimeptr\fP\fB);
|
||
|
.br
|
||
|
\fP
|
||
|
.LP
|
||
|
\fBchar *asctime_r(const struct tm *restrict\fP \fItm\fP\fB, char
|
||
|
*restrict\fP \fIbuf\fP\fB);
|
||
|
\fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
For \fIasctime\fP(): 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
|
||
|
IEEE\ Std\ 1003.1-2001 defers to the ISO\ C standard.
|
||
|
.LP
|
||
|
The \fIasctime\fP() function shall convert the broken-down time in
|
||
|
the structure pointed to by \fItimeptr\fP into a string in
|
||
|
the form:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBSun Sep 16 01:03:52 1973\\n\\0
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
using the equivalent of the following algorithm:
|
||
|
.sp
|
||
|
.RS
|
||
|
.nf
|
||
|
|
||
|
\fBchar *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];
|
||
|
.sp
|
||
|
|
||
|
sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\\n",
|
||
|
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;
|
||
|
}
|
||
|
\fP
|
||
|
.fi
|
||
|
.RE
|
||
|
.LP
|
||
|
The \fBtm\fP structure is defined in the \fI<time.h>\fP header.
|
||
|
.LP
|
||
|
The
|
||
|
\fIasctime\fP(), \fIctime\fP(), \fIgmtime\fP(), and
|
||
|
\fIlocaltime\fP() functions shall return values in one of two static
|
||
|
objects: a
|
||
|
broken-down time structure and an array of type \fBchar\fP. Execution
|
||
|
of any of the functions may overwrite the information
|
||
|
returned in either of these objects by any of the other functions.
|
||
|
.LP
|
||
|
The \fIasctime\fP() function need not be reentrant. A function that
|
||
|
is not required to be reentrant is not required to be
|
||
|
thread-safe.
|
||
|
.LP
|
||
|
The \fIasctime_r\fP() function shall convert the broken-down time
|
||
|
in the structure pointed to by \fItm\fP into a string (of the
|
||
|
same form as that returned by \fIasctime\fP()) that is placed in the
|
||
|
user-supplied buffer pointed to by \fIbuf\fP (which shall
|
||
|
contain at least 26 bytes) and then return \fIbuf\fP.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
Upon successful completion, \fIasctime\fP() shall return a pointer
|
||
|
to the string.
|
||
|
.LP
|
||
|
Upon successful completion, \fIasctime_r\fP() shall return a pointer
|
||
|
to a character string containing the date and time. This
|
||
|
string is pointed to by the argument \fIbuf\fP. If the function is
|
||
|
unsuccessful, it shall return NULL.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
No errors are defined.
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
Values for the broken-down time structure can be obtained by calling
|
||
|
\fIgmtime\fP() or
|
||
|
\fIlocaltime\fP(). This function is included for compatibility with
|
||
|
older
|
||
|
implementations, and does not support localized date and time formats.
|
||
|
Applications should use \fIstrftime\fP() to achieve maximum portability.
|
||
|
.LP
|
||
|
The \fIasctime_r\fP() 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
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIclock\fP() , \fIctime\fP() , \fIdifftime\fP() , \fIgmtime\fP()
|
||
|
, \fIlocaltime\fP()
|
||
|
, \fImktime\fP() , \fIstrftime\fP() , \fIstrptime\fP() , \fItime\fP()
|
||
|
, \fIutime\fP() , the Base
|
||
|
Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<time.h>\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 .
|