path: root/usr/src/man/man3c/ctime.3c

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
.\"
.TH CTIME 3C "May 27, 2005"
.SH NAME
ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime, asctime_r,
tzset \- convert date and time to string
.SH SYNOPSIS
.LP
.nf
#include <time.h>

\fBchar *\fR\fBctime\fR(\fBconst time_t *\fR\fIclock\fR);
.fi

.LP
.nf
\fBstruct tm *\fR\fBlocaltime\fR(\fBconst time_t *\fR\fIclock\fR);
.fi

.LP
.nf
\fBstruct tm *\fR\fBgmtime\fR(\fBconst time_t *\fR\fIclock\fR);
.fi

.LP
.nf
\fBchar *\fR\fBasctime\fR(\fBconst struct tm *\fR\fItm\fR);
.fi

.LP
.nf
extern time_t timezone, altzone;
extern int daylight;
extern char *tzname[2];

\fBvoid\fR \fBtzset\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBchar *\fR\fBctime_r\fR(\fBconst time_t *\fR\fIclock\fR, \fBchar *\fR\fIbuf\fR, \fBint\fR \fIbuflen\fR);
.fi

.LP
.nf
\fBstruct tm *\fR\fBlocaltime_r\fR(\fBconst time_t *restrict\fR \fIclock\fR,
     \fBstruct tm *restrict\fR \fIres\fR);
.fi

.LP
.nf
\fBstruct tm *\fR\fBgmtime_r\fR(\fBconst time_t *restrict\fR \fIclock\fR,
     \fBstruct tm *restrict\fR \fIres\fR);
.fi

.LP
.nf
\fBchar *\fR\fBasctime_r\fR(\fBconst struct tm *restrict\fR \fItm\fR, \fBchar *restrict\fR \fIbuf\fR,
     \fBint\fR \fIbuflen\fR);
.fi

.SS "Standard conforming"
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ]

\fBchar *\fR\fBctime_r\fR(\fBconst time_t *\fR\fIclock\fR, \fBchar *\fR\fIbuf\fR);
.fi

.LP
.nf
\fBchar *\fR\fBasctime_r\fR(\fBconst struct tm *\fR\fItm\fR, \fBchar *\fR\fIbuf\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBctime()\fR function converts the time pointed to by \fIclock\fR,
representing the time in seconds since the Epoch (00:00:00 UTC, January 1,
1970), to local time in the form of a 26-character string, as shown below. Time
zone and daylight savings corrections are made before string generation. The
fields are in constant width:
.sp
.LP
Fri Sep 13 00:00:00 1986\en\e0
.sp
.LP
The \fBctime()\fR function is equivalent to:
.sp
.LP
\fBasctime(localtime(\fR\fIclock\fR\fB\fR\fB))\fR
.sp
.LP
The \fBctime()\fR, \fBasctime()\fR, \fBgmtime()\fR, and \fBlocaltime()\fR
functions return values in one of two thread-specific data objects: a
broken-down time structure and an array of \fBchar\fR. Execution of any of the
functions can overwrite the information returned in either of these objects by
any of the other functions executed by the same thread.
.sp
.LP
The \fBctime_r()\fR function has the same functionality as \fBctime()\fR except
that the caller must supply a buffer \fIbuf\fR with length \fIbuflen\fR to
store the result; \fIbuf\fR must be at least 26 bytes. The standard-conforming
\fBctime_r()\fR function does not take a \fIbuflen\fR parameter.
.sp
.LP
The \fBlocaltime()\fR and \fBgmtime()\fR functions return pointers to \fBtm\fR
structures (see below). The \fBlocaltime()\fR function corrects for the main
time zone and possible alternate ("daylight savings") time zone; the
\fBgmtime()\fR function converts directly to Coordinated Universal Time (UTC),
which is what the UNIX system uses internally.
.sp
.LP
The \fBlocaltime_r()\fR and \fBgmtime_r()\fR functions have the same
functionality as \fBlocaltime()\fR and \fBgmtime()\fR respectively, except that
the caller must supply a buffer \fIres\fR to store the result.
.sp
.LP
The \fBasctime()\fR function converts a \fBtm\fR structure to a 26-character
string, as shown in the previous example, and returns a pointer to the string.
.sp
.LP
The \fBasctime_r()\fR function has the same functionality as \fBasctime()\fR
except that the caller must supply a buffer \fIbuf\fR with length \fIbuflen\fR
for the result to be stored.  The \fIbuf\fR argument must be at least 26 bytes.
The standard-conforming \fBasctime_r()\fR function does not take a \fIbuflen\fR
parameter.  The \fBasctime_r()\fR function returns a pointer to \fIbuf\fR upon
success.  In case of failure, \fINULL\fR is returned and \fBerrno\fR is set.
.sp
.LP
Declarations of all the functions and externals, and the \fBtm\fR structure,
are in the <\fBtime.h\fR> header. The members of the \fBtm\fR structure are:
.sp
.in +2
.nf
int   tm_sec;    /* seconds after the minute \(em [0, 60] */
                 /* for leap seconds */
int   tm_min;    /* minutes after the hour \(em [0, 59] */
int   tm_hour;   /* hour since midnight \(em [0, 23] */
int   tm_mday;   /* day of the month \(em [1, 31] */
int   tm_mon;    /* months since January \(em [0, 11] */
int   tm_year;   /* years since 1900 */
int   tm_wday;   /* days since Sunday \(em [0, 6] */
int   tm_yday;   /* days since January 1 \(em [0, 365] */
int   tm_isdst;  /* flag for alternate daylight savings time */
.fi
.in -2

.sp
.LP
The value of \fBtm_isdst\fR is positive if daylight savings time is in effect,
zero if daylight savings time is not in effect, and negative if the information
is not available. Previously, the value of \fBtm_isdst\fR was defined as
non-zero if daylight savings was in effect.
.sp
.LP
The external \fBtime_t\fR variable \fBaltzone\fR contains the difference, in
seconds, between Coordinated Universal Time and the alternate time zone. The
external variable \fBtimezone\fR contains the difference, in seconds, between
UTC and local standard time. The external variable \fBdaylight\fR indicates
whether time should reflect daylight savings time. Both \fBtimezone\fR and
\fBaltzone\fR default to 0 (UTC). The external variable \fBdaylight\fR is
non-zero if an alternate time zone exists. The time zone names are contained in
the external variable \fBtzname\fR, which by default is set to:
.sp
.LP
char *tzname[2] = { "GMT", "\|" };
.sp
.LP
These functions know about the peculiarities of this conversion for various
time periods for the \fBU.S.\fR (specifically, the years 1974, 1975, and 1987).
They start handling the new daylight savings time starting with the first
Sunday in April, 1987.
.sp
.LP
The \fBtzset()\fR function uses the contents of the environment variable
\fBTZ\fR to override the value of the different external variables. It is
called by \fBasctime()\fR and can also be called by the user. If \fBTZ\fR is
not specified or has an invalid setting, \fBtzset()\fR uses \fBGMT0\fR. See
\fBenviron\fR(7) for a description of the \fBTZ\fR environment variable.
.sp
.LP
Starting and ending times are relative to the current local time zone. If the
alternate time zone start and end dates and the time are not provided, the days
for the United States that year will be used and the time will be 2 AM. If the
start and end dates are provided but the time is not provided, the time will be
2 AM. The effects of \fBtzset()\fR change the values of the external variables
\fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR.
.sp
.LP
Note that in most installations, \fBTZ\fR is set to the correct value by
default when the user logs on, using the local \fB/etc/default/init\fR file
(see \fBTIMEZONE\fR(5)).
.SH RETURN VALUES
.sp
.LP
Upon successful completion, the \fBgmtime()\fR and \fBlocaltime()\fR functions
return a pointer to a \fBstruct tm\fR. If an error is detected, \fBgmtime()\fR
and \fBlocaltime()\fR return a null pointer.
.sp
.LP
Upon successful completion, the \fBgmtime_r()\fR and \fBlocaltime_r()\fR
functions return the address of the structure pointed to by the \fIres\fR
argument. If an error is detected, \fBgmtime_r()\fR and \fBlocaltime_r()\fR
return a null pointer and set \fBerrno\fR to indicate the error.
.SH ERRORS
.sp
.LP
The \fBctime_r()\fR and \fBasctime_r()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBERANGE\fR\fR
.ad
.RS 10n
The length of the buffer supplied by the caller is not large enough to store
the result.
.RE

.sp
.LP
The \fBgmtime()\fR, \fBgmtime_r()\fR, \fBlocaltime()\fR, and
\fBlocaltime_r()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 13n
The result cannot be represented.
.RE

.SH USAGE
.sp
.LP
These functions do not support localized date and time formats. The
\fBstrftime\fR(3C) function can be used when localization is required.
.sp
.LP
The \fBlocaltime()\fR, \fBlocaltime_r()\fR, \fBgmtime()\fR, \fBgmtime_r()\fR,
\fBctime()\fR, and \fBctime_r()\fR functions assume Gregorian dates. Times
before the adoption of the Gregorian calendar will not match historial records.
.SH EXAMPLES
.LP
\fBExample 1 \fRExamples of the \fBtzset()\fR function.
.sp
.LP
The \fBtzset()\fR function scans the contents of the environment variable and
assigns the different fields to the respective variable. For example, the most
complete setting for New Jersey in 1986 could be:

.sp
.in +2
.nf
EST5EDT4,116/2:00:00,298/2:00:00
.fi
.in -2

.sp
.LP
or simply

.sp
.in +2
.nf
EST5EDT
.fi
.in -2

.sp
.LP
An example of a southern hemisphere setting such as the Cook Islands could be

.sp
.in +2
.nf
KDT9:30KST10:00,63/5:00,302/20:00
.fi
.in -2

.sp
.LP
In the longer version of the New Jersey example of \fBTZ,\fR
\fBtzname\fR[\fB0\fR] is EST, \fBtimezone\fR is set to 5*60*60,
\fBtzname\fR[\fB1\fR] is EDT, \fBaltzone\fR is set to 4*60*60, the starting
date of the alternate time zone is the 117th day at 2 AM, the ending date of
the alternate time zone is the 299th day at 2 AM (using zero-based Julian
days), and \fBdaylight\fR is set positive. Starting and ending times are
relative to the current local time zone. If the alternate time zone start and
end dates and the time are not provided, the days for the United States that
year will be used and the time will be 2 AM. If the start and end dates are
provided but the time is not provided, the time will be 2 AM. The effects of
\fBtzset()\fR are thus to change the values of the external variables
\fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR. The
\fBctime()\fR, \fBlocaltime()\fR, \fBmktime()\fR, and \fBstrftime()\fR
functions also update these external variables as if they had called
\fBtzset()\fR at the time specified by the \fBtime_t\fR or \fBstruct tm\fR
value that they are converting.

.SH BUGS
.sp
.LP
The \fBzoneinfo\fR timezone data files do not transition past Tue Jan 19
03:14:07 2038 UTC.  Therefore for 64-bit applications using \fBzoneinfo\fR
timezones, calculations beyond this date might not use the correct offset from
standard time, and could return incorrect values. This affects the 64-bit
version of \fBlocaltime()\fR, \fBlocaltime_r()\fR, \fBctime()\fR, and
\fBctime_r()\fR.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Standard
_
MT-Level	MT-Safe with exceptions
.TE

.sp
.LP
The \fBasctime()\fR, \fBctime()\fR, \fBgmtime()\fR, and \fBlocaltime()\fR
functions are safe to use in multithread applications because they employ
thread-specific data. However, their use is discouraged because standards do
not require them to be thread-safe. The \fBasctime_r()\fR and \fBgmtime_r()\fR
functions are MT-Safe. The \fBctime_r()\fR, \fBlocaltime_r()\fR, and
\fBtzset()\fR functions are MT-Safe in multithread applications, as long as no
user-defined function directly modifies one of the following variables:
\fBtimezone\fR, \fBaltzone\fR, \fBdaylight\fR, and \fBtzname\fR. These four
variables are not MT-Safe to access. They are modified by the \fBtzset()\fR
function in an MT-Safe manner. The \fBmktime()\fR, \fBlocaltime_r()\fR, and
\fBctime_r()\fR functions call \fBtzset()\fR.
.SH SEE ALSO
.sp
.LP
.BR time (2),
.BR Intro (3),
.BR getenv (3C),
.BR mktime (3C),
.BR printf (3C),
.BR putenv (3C),
.BR setlocale (3C),
.BR strftime (3C),
.BR TIMEZONE (5),
.BR attributes (7),
.BR environ (7),
.BR standards (7)
.SH NOTES
.sp
.LP
When compiling multithreaded programs, see \fBIntro\fR(3).
.sp
.LP
The return values for \fBasctime()\fR, \fBctime()\fR, \fBgmtime()\fR, and
\fBlocaltime()\fR point to thread-specific data whose content is overwritten by
each call by the same thread.
.sp
.LP
Setting the time during the interval of change from \fBtimezone\fR to
\fBaltzone\fR or vice versa can produce unpredictable results. The system
administrator must change the Julian start and end days annually.
.sp
.LP
If \fBtzset()\fR has previously evaluated the timezone identified by the value
of the \fBTZ\fR  environment variable, \fBtzset()\fR can reuse the previous
settings of the external variables \fBaltzone\fR, \fBdaylight\fR,
\fBtimezone\fR, and \fBtzname\fR[] associated with that timezone.
.sp
.LP
Solaris 2.4 and earlier releases provided definitions of the \fBctime_r()\fR,
\fBlocaltime_r()\fR, \fBgmtime_r()\fR, and \fBasctime_r()\fR functions as
specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
interface for \fBctime_r()\fR and \fBasctime_r()\fR. Support for the Draft 6
interface is provided for compatibility only and might not be supported in
future releases. New applications and libraries should use the
standard-conforming interface.
.sp
.LP
For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and
\fB_REENTRANT\fR flags are automatically turned on by defining the
\fB_POSIX_C_SOURCE\fR flag with a value >= 199506L.
.sp
.LP
In Solaris 10, \fBgmtime()\fR, \fBgmtime_r()\fR, \fBlocaltime()\fR, and
\fBlocaltime_r()\fR were updated to return a null pointer if an error is
detected. This change was based on the SUSv3 specification. See
\fBstandards\fR(7).