117 lines
3.7 KiB
Groff
117 lines
3.7 KiB
Groff
.\" 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).
|