.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "ASCTIME" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" asctime 
.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 \- 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 .