'\"macro stdmacro
.if n .pH g3c.ctime @(#)ctime	40.23 of 10/24/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} ctime 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} ctime 3C "C Programming Language Utilities"
.if \nX=2 .ds x} ctime 3C "" "\&"
.if \nX=3 .ds x} ctime "" "" "\&"
.TH \*(x}
.SH NAME
\f4ctime\f1, \f4localtime\f1, \f4gmtime\f1, \f4asctime\f1, \f4tzset\f1 \- convert date and time to string
.SH SYNOPSIS
\f4#include <time.h>\f1
.PP
\f4char \(**ctime (const time_t \(**clock);\f1
.PP
\f4struct tm \(**localtime (const time_t \(**clock);\f1
.PP
\f4struct tm \(**gmtime (const time_t \(**clock);\f1
.PP
\f4char \(**asctime (const struct tm \(**tm);\f1
.PP
\f4extern time_t timezone, altzone;\f1
.PP
\f4extern int daylight;\f1
.PP
\f4extern char \(**tzname[2];\f1
.PP
\f4void tzset (void);\f1
.SH DESCRIPTION
\f4ctime\fP,
\f4localtime\fP,
and
\f4gmtime\fP
accept arguments of type
\f4time_t\f1,
pointed to by
\f4clock\fP,
representing the time in seconds since
00:00:00 \s-1UTC\s0, January 1, 1970.
\f4ctime\fP returns a pointer to a 26-character string as shown below.
Time zone and daylight savings corrections
are made before the string is generated.
The fields are constant in width:
.PP
.RS
\f(CW Fri Sep 13 00:00:00 1986\\n\\0\f1  
.RE
.PP
\f4localtime\fP
and
\f4gmtime\fP
return pointers to \f4tm\fP structures, described below.
\f4localtime\fP
corrects for the main time zone and possible alternate (``daylight savings'')
time zone;
\f4gmtime\fP
converts directly to Coordinated Universal Time (\s-1UTC\s0), which is the
time the \s-1UNIX\s0 system uses internally.
.PP
\f4asctime\fP
converts a \f4tm\fP structure to a 26-character string,
as shown in the above example, and returns a pointer to the string.
.PP
Declarations of all the functions and externals, and the \f4tm\fP structure,
are in the
\f4time.h\fP
header file.
The structure declaration is:
.RS
.PP
.nf
\f4struct	tm {	
	int	tm_sec;	/\(** seconds after the minute \(em [0, 61] \(**/
					/\(** 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 \(**/
};\fP
.fi
.RE
.PP
The value of \f4tm_isdst\fP 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 \f4tm_isdst\fP was defined as
non-zero if daylight savings time was in effect.)
.PP
The external
\f4time_t\fP 
variable 
\f4altzone\fP
contains the difference, in seconds, between Coordinated Universal Time  
and the alternate time zone.
The external variable \f4timezone\fP contains the difference, in seconds,
between \s-1UTC\s+1 and local standard time. The external variable \f4daylight\fP
indicates whether time should reflect daylight savings time.
Both
\f4timezone\fP
and
\f4altzone\fP
default to 0 (\s-1UTC\s0).
The external variable \f4daylight\fP
is non-zero if an alternate time zone exists.
The time zone names are contained in the external variable 
\f4tzname\fP,
which by default is set to:
.PP
	\f4char \(**tzname[2] = { "\s-1GMT\s0", "\s-1   \s0" };\f1
.PP
These functions know about the peculiarities
of this conversion for various time periods for the
.SM U.S.
(specifically, the years 1974, 1975, and 1987).
They will handle the new daylight savings time
starting with the first Sunday in April, 1987.
.PP
\f4tzset\fP
uses the contents of the environment variable
\f4TZ\f1
to override the value of the different external variables.
The function \f4tzset\f1 is called by \f4asctime\f1 and may also be called by the
user.
See \f4environ\f1(5) for a description of the \f4TZ\f1 environment variable.
.PP
\f4tzset\fP
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
.PP
\f4
	EST5EDT4,116/2:00:00,298/2:00:00\fP
.PP
or simply
.PP
.BR
	\f4EST5EDT\fP
.PP
An example of a southern hemisphere setting such as the Cook Islands
could be
.PP
.BR
	\f4KDT9:30KST10:00,63/5:00,302/20:00\f1
.PP
In the longer version of the New Jersey example of 
\f4TZ\^,\f1
\f4tzname\f1[\f20\f1] is \s-1EST\s0,
\f4timezone\fP
will be set to 5\(**60\(**60,
\f4tzname\f1[\f21\f1] is \s-1EDT\s0,
\f4altzone\fP
will be set to 4\(**60\(**60,
the starting date of the alternate time zone is the 117th
day at 2 \s-1AM\s+1, the ending date of the alternate time zone is the 299th day
at 2 \s-1AM\s+1 (using zero-based Julian days), and
\f4daylight\fP
will be set positive.
Starting and ending times are relative to the alternate 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 \s-1AM\s+1.
If the start and end dates are provided but the time is not provided,
the time will be 2 \s-1AM\s+1.
The effects of 
\f4tzset\fP
are thus to change the values of the external variables
\f4timezone\fP, \f4altzone\fP, \f4daylight\fP, and \f4tzname\fP.
\f4ctime\fP, \f4localtime\fP, \f4mktime\fP, and \f4strftime\fP will also
update these external variables as if they had called \f4tzset\fP at the time
specified by the \f4time_t\fP or \f4struct tm\fP value that they are converting.
.sp .5
Note that in most installations,
.SM
\f4TZ\f1
is set to the correct value by default when the user logs on,
via the local \f4/etc/profile\fP file
[see
\f4profile\fP(4)
and 
\f4timezone\fP(4)].
.SH FILES
\f4/usr/lib/locale/\f2language\f4/LC_TIME\f1 \- file containing locale specific date and
time information
.SH "SEE ALSO"
\f4time\fP(2), \f4getenv\fP(3C), \f4mktime\fP(3C), \f4putenv\fP(3C),
\f4printf\fP(3S), \f4setlocale\fP(3C), \f4strftime\fP(3C), \f4cftime\fP(4),
\f4profile\fP(4), \f4timezone\fP(4), \f4environ\fP(5).
.SH NOTES
The return values for
\f4ctime\fP,
\f4localtime\fP,
and
\f4gmtime\fP
point to static data
whose content is overwritten by each call.
.PP
Setting the time during the interval of change from \f4timezone\fP
to \f4altzone\f1 or vice versa can produce unpredictable results.
The system administrator must change the Julian start and end days annually.
.\"	@(#)ctime.3c	6.3 of 10/20/83
.Ee
