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.8 (Berkeley) 4/2/87
.\"
.TH CTIME 3  "April 2, 1987"
.UC 4
.SH NAME
ctime, localtime, gmtime, asctime, tzset \-  convert date and time to ASCII
.SH SYNOPSIS
.nf
.ft B
#include <sys/types.h>
#include <time.h>

void tzset(void)
char *ctime(const time_t *\fIclock\fP)
char *asctime(const struct tm *\fItm\fP)
struct tm *localtime(const time_t *\fIclock\fP)
struct tm *gmtime(const time_t *\fIclock\fP)
.fi
.SH DESCRIPTION
\fBTzset\fP uses the value of the environment variable \fBTZ\fP to
set up the time conversion information used by \fBlocaltime\fP.
.PP
If \fBTZ\fP does not appear in the environment, the \fBTZDEFAULT\fP
file (as defined in \fI<tzfile.h>\fP) is used by \fBlocaltime\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 \fBtzfile\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 \fBtzfile.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.
See
.BR TZ (5)
for a proper description of the
.B TZ
variable.
.PP
\fBCtime\fP converts a time value, pointed to by \fIclock\fP,
such as returned by \fBtime\fP(2) into ASCII and returns a pointer
to a 26-character string in the following form.  All the fields
have constant width.
.PP
.RS
.nf
Sun Sep 16 01:03:52 1973\en\e0
.fi
.RE
.PP
.B Localtime
and
.B gmtime
return pointers to structures containing
the broken-down time.
.B Localtime
corrects for the time zone and possible daylight savings time;
.B gmtime
converts directly to GMT, which is the time UNIX uses.
.B 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 */
	long tm_gmtoff;	/* offset from GMT in seconds */
	char **tm_zone;	/* abbreviation of timezone name */
};
.fi
.RE
.PP
\fBTm_isdst\fP is non-zero if a time zone adjustment such as Daylight
Savings time is in effect.
.PP
\fBTm_gmtoff\fP is the offset (in seconds) of the time represented
from GMT, with positive values indicating East of Greenwich.
.SH FILES
.ta \w'/usr/lib/zoneinfo\0\0'u
/usr/lib/zoneinfo	time zone information directory
.br
/etc/localtime	local time zone file
.SH SEE ALSO
.BR time (2),
.BR getenv (3),
.BR tzfile (5),
.BR TZ (5),
.BR environ (7),
.BR zic (8).
.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 \fBtzset\fP).