.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "CTIME" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" ctime 
.SH NAME
ctime, ctime_r \- convert a time value to a date and time string
.SH SYNOPSIS
.LP
\fB#include <time.h>
.br
.sp
char *ctime(const time_t *\fP\fIclock\fP\fB);
.br
\fP
.LP
\fBchar *ctime_r(const time_t *\fP\fIclock\fP\fB, char *\fP\fIbuf\fP\fB);
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
For \fIctime\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 \fIctime\fP() function shall convert the time pointed to by \fIclock\fP,
representing time in seconds since the Epoch, to
local time in the form of a string. It shall be equivalent to:
.sp
.RS
.nf

\fBasctime(localtime(clock))
\fP
.fi
.RE
.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 \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 \fIctime\fP() function need not be reentrant. A function that
is not required to be reentrant is not required to be
thread-safe. 
.LP
The \fIctime_r\fP() function shall convert the calendar time pointed
to by \fIclock\fP to local time in exactly the same form as
\fIctime\fP() and put the string into the array pointed to by \fIbuf\fP
(which shall be at least 26 bytes in size) and return
\fIbuf\fP.
.LP
Unlike \fIctime\fP(), the thread-safe version \fIctime_r\fP() is not
required to set \fItzname\fP. 
.SH RETURN VALUE
.LP
The \fIctime\fP() function shall return the pointer returned by \fIasctime\fP()
with
that broken-down time as an argument.
.LP
Upon successful completion, \fIctime_r\fP() shall return a pointer
to the string pointed to by \fIbuf\fP. When an error is
encountered, a null pointer shall be returned. 
.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(). The \fIctime\fP() function is included for compatibility
with older
implementations, and does not support localized date and time formats.
Applications should use the \fIstrftime\fP() function to achieve maximum
portability.
.LP
The \fIctime_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
\fIasctime\fP() , \fIclock\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 .