install C version of _doprnt

[unix-history] / usr / src / lib / libc / gen / ctime.3

.\" Copyright (c) 1980 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)ctime.3	6.9 (Berkeley) %G%
.\"
.TH CTIME 3  ""
.UC 4
.SH NAME
ctime, localtime, gmtime, asctime, timezone, tzset \-  convert date and time to ASCII
.SH SYNOPSIS
.nf
.B void tzset()
.PP
.B char *ctime(clock)
.B time_t *clock;
.PP
.B #include <time.h>
.PP
.B char *asctime(tm)
.B struct tm *tm;
.PP
.B struct tm *localtime(clock)
.B time_t *clock;
.PP
.B struct tm *gmtime(clock)
.B time_t *clock;
.PP
.B char *timezone(zone, dst)
.fi
.fi
.SH DESCRIPTION
\fITzset\fP uses the value of the environment variable \fBTZ\fP to
set up the time conversion information used by \fIlocaltime\fP.
.PP
If \fBTZ\fP does not appear in the environment, the \fBTZDEFAULT\fP
file (as defined in \fItzfile.h\fP) is used by \fIlocaltime\fP.  If
this file fails for any reason, the GMT offset as provided by the
kernel is used.  In this case, DST is ignored, resulting in the time
being incorrect by some amount if DST is currently in effect.  If
this fails for any reason, GMT is used.
.PP
If \fBTZ\fP appears in the environment but its value is a null string,
Greenwich Mean Time is used; if \fBTZ\fP appears and begins with a
slash, it is used as the absolute pathname of the \fItzfile\fP(5)-format
file from which to read the time conversion information; if \fBTZ\fP
appears and begins with a character other than a slash, it's used as
a pathname relative to the system time conversion information directory,
defined as \fBTZDIR\fP in the include file \fItzfile.h\fP.  If this file
fails for any reason, the GMT offset as provided by the kernel is
used, as described above.  If this fails for any reason, GMT is used.
.PP
Programs that always wish to use local wall clock time should explicitly
remove the environmental variable \fBTZ\fP with \fIunsetenv\fP(3).
.PP
\fICtime\fP converts a long integer, pointed to by \fIclock\fP,
such as returned by \fItime\fP(3), into ASCII and returns a pointer
to a 26-character string in the following form.  All the fields
have constant width.
.PP
    Sun Sep 16 01:03:52 1973\\n\\0
.PP
.I Localtime
and
.I gmtime
return pointers to structures containing
the broken-down time.
.I Localtime
corrects for the time zone and possible daylight savings time;
.I gmtime
converts directly to GMT, which is the time UNIX uses.
.I Asctime
converts a broken-down time to ASCII and returns a pointer
to a 26-character string.
.PP
The structure declaration from the include file is:
.PP
.RS
.nf
.nr .0 .8i+\w'int tm_isdst'u
.ta .5i \n(.0u \n(.0u+\w'/* 0-000'u+1n
struct tm {
	int tm_sec;	/* 0-59	seconds */
	int tm_min;	/* 0-59	minutes */
	int tm_hour;	/* 0-23	hour */
	int tm_mday;	/* 1-31	day of month */
	int tm_mon;	/* 0-11	month */
	int tm_year;	/* 0-	year \- 1900 */
	int tm_wday;	/* 0-6	day of week (Sunday = 0) */
	int tm_yday;	/* 0-365	day of year */
	int tm_isdst;	/* flag:	daylight savings time in effect */
	char **tm_zone;	/* abbreviation of timezone name */
	long tm_gmtoff;	/* offset from GMT in seconds */
};
.fi
.RE
.PP
\fITm_isdst\fP is non-zero if a time zone adjustment such as Daylight
Savings time is in effect.
.PP
\fITm_gmtoff\fP is the offset (in seconds) of the time represented
from GMT, with positive values indicating East of Greenwich.
.PP
\fITimezone\fP remains for compatibility reasons only; it's impossible to
reliably map timezone's arguments (\fIzone\fP, a "minutes west of GMT" value
and \fIdst\fP, a "daylight saving time in effect" flag) to a time zone
abbreviation.
.PP
If the environmental string \fITZNAME\fP exists, \fItimezone\fP returns
its value, unless it consists of two comma separated strings, in which
case the second string is returned if \fIdst\fP is non-zero, else
the first string.  If \fITZNAME\fP doesn't exist, \fIzone\fP is checked
for equality with a built-in table of values, in which case \fItimezone\fP
returns the time zone or daylight time zone abbreviation associated with
that value.  If the requested \fIzone\fP does not appear in the table, the
difference from GMT is returned; e.g. in Afghanistan,
\fItimezone(-(60*4+30), 0)\fP is appropriate because it is 4:30 ahead of
GMT, and the string \fBGMT+4:30\fP is returned.  Programs that in the
past used the \fItimezone\fP function should return the zone name as
set by \fIlocaltime\fP to assure correctness.
.SH FILES
.ta \w'/etc/zoneinfo/localtime\0\0'u
/etc/zoneinfo	time zone information directory
.br
/etc/zoneinfo/localtime	local time zone file
.SH SEE ALSO
gettimeofday(2), getenv(3), time(3), tzfile(5), environ(7)
.SH NOTE
The return values point to static data whose content is overwritten by
each call.  The \fBtm_zone\fP field of a returned \fBstruct tm\fP
points to a static array of characters, which will also be overwritten
at the next call (and by calls to \fItzset\fP).