261 lines
6.1 KiB
Groff
261 lines
6.1 KiB
Groff
.\" $NetBSD: ctime.3,v 1.20 2000/07/10 12:39:39 kleink Exp $
|
|
.TH CTIME 3
|
|
.SH NAME
|
|
asctime, asctime_r, ctime, ctime_r, difftime, gmtime, gmtime_r, localtime, localtime_r, mktime \- convert date and time to ASCII
|
|
.SH LIBRARY
|
|
Standard C Library (libc, -lc)
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <time.h>
|
|
.PP
|
|
.B extern char *tzname[2];
|
|
.PP
|
|
.B char *ctime(const time_t *clock);
|
|
.B char *ctime_r(const time_t *clock, char *buf);
|
|
.PP
|
|
.B double difftime(time_t time1, time_t time0);
|
|
.PP
|
|
.B char *asctime(const struct tm *tm);
|
|
.B char *asctime_r(const struct tm *, char *buf);
|
|
.PP
|
|
.B struct tm *localtime(const time_t *clock);
|
|
.B struct tm *localtime_r(const time_t *clock, struct tm *result);
|
|
.PP
|
|
.B struct tm *gmtime(const time_t *clock);
|
|
.B struct tm *gmtime_r(const time_t *clock, struct tm *result);
|
|
.PP
|
|
.B time_t mktime(struct tm *tm);
|
|
.PP
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.I Ctime\^
|
|
converts a long integer, pointed to by
|
|
.IR clock ,
|
|
representing the time in seconds since
|
|
00:00:00 UTC, 1970-01-01,
|
|
and returns a pointer to a
|
|
26-character string
|
|
of the form
|
|
.br
|
|
.ce
|
|
.eo
|
|
Thu Nov 24 18:22:48 1986\n\0
|
|
.ec
|
|
.br
|
|
All the fields have constant width.
|
|
.PP
|
|
The
|
|
.I ctime_r\^
|
|
function provides the same functionality as
|
|
.I ctime\^
|
|
differing in that the caller must supply a buffer area
|
|
.IR buf
|
|
with a size of at least 26 bytes, in which the result is stored.
|
|
.PP
|
|
.IR Localtime\^
|
|
and
|
|
.I gmtime\^
|
|
return pointers to ``tm'' structures, described below.
|
|
.I Localtime\^
|
|
corrects for the time zone and any time zone adjustments
|
|
(such as Daylight Saving Time in the U.S.A.).
|
|
After filling in the ``tm'' structure,
|
|
.I localtime
|
|
sets the
|
|
.BR tm_isdst 'th
|
|
element of
|
|
.B tzname
|
|
to a pointer to an
|
|
ASCII string that's the time zone abbreviation to be used with
|
|
.IR localtime 's
|
|
return value.
|
|
.PP
|
|
.I Gmtime\^
|
|
converts to Coordinated Universal Time.
|
|
.PP
|
|
The
|
|
.I gmtime_r\^
|
|
and
|
|
.I localtime_r\^
|
|
functions provide the same functionality as
|
|
.I gmtime\^
|
|
and
|
|
.I localtime\^
|
|
differing in that the caller must supply a buffer area
|
|
.IR result
|
|
in which the result is stored; also,
|
|
.I localtime_r\^
|
|
does not imply initialization of the local time conversion information;
|
|
the application may need to do so by calling
|
|
.IR tzset .
|
|
.PP
|
|
.I Asctime\^
|
|
converts a time value contained in a
|
|
``tm'' structure to a 26-character string,
|
|
as shown in the above example,
|
|
and returns a pointer
|
|
to the string.
|
|
.PP
|
|
The
|
|
.I asctime_r\^
|
|
function provides the same functionality as
|
|
.I asctime\^
|
|
differing in that the caller must supply a buffer area
|
|
.IR buf
|
|
with a size of at least 26 bytes, in which the result is stored.
|
|
.PP
|
|
.I Mktime\^
|
|
converts the broken-down time,
|
|
expressed as local time,
|
|
in the structure pointed to by
|
|
.I tm
|
|
into a calendar time value with the same encoding as that of the values
|
|
returned by the
|
|
.I time
|
|
function.
|
|
The original values of the
|
|
.B tm_wday
|
|
and
|
|
.B tm_yday
|
|
components of the structure are ignored,
|
|
and the original values of the other components are not restricted
|
|
to their normal ranges.
|
|
(A positive or zero value for
|
|
.B tm_isdst
|
|
causes
|
|
.I mktime
|
|
to presume initially that summer time (for example, Daylight Saving Time
|
|
in the U.S.A.)
|
|
respectively,
|
|
is or is not in effect for the specified time.
|
|
A negative value for
|
|
.B tm_isdst
|
|
causes the
|
|
.I mktime
|
|
function to attempt to divine whether summer time is in effect
|
|
for the specified time.)
|
|
On successful completion, the values of the
|
|
.B tm_wday
|
|
and
|
|
.B tm_yday
|
|
components of the structure are set appropriately,
|
|
and the other components are set to represent the specified calendar time,
|
|
but with their values forced to their normal ranges; the final value of
|
|
.B tm_mday
|
|
is not set until
|
|
.B tm_mon
|
|
and
|
|
.B tm_year
|
|
are determined.
|
|
.I Mktime\^
|
|
returns the specified calendar time;
|
|
If the calendar time cannot be represented,
|
|
it returns
|
|
.BR -1 .
|
|
.PP
|
|
.I Difftime\^
|
|
returns the difference between two calendar times,
|
|
.RI ( time1
|
|
-
|
|
.IR time0 ),
|
|
expressed in seconds.
|
|
.PP
|
|
Declarations of all the functions and externals, and the ``tm'' structure,
|
|
are in the
|
|
.B <time.h>\^
|
|
header file.
|
|
The structure (of type)
|
|
.B struct tm
|
|
includes the following fields:
|
|
.RS
|
|
.PP
|
|
.nf
|
|
.ta .5i +\w'long tm_gmtoff;\0\0'u
|
|
int tm_sec; /\(** seconds after the minute [0,61] \(**/
|
|
int tm_min; /\(** minutes after the hour [0,59] \(**/
|
|
int tm_hour; /\(** hours since midnight [0,23] \(**/
|
|
int tm_mday; /\(** day of the month [1,31] \(**/
|
|
int tm_mon; /\(** months since January [0,11] \(**/
|
|
int tm_year; /\(** years since 1900 \(**/
|
|
int tm_wday; /\(** day of week [0,6] (Sunday = 0) \(**/
|
|
int tm_yday; /\(** day of year [0,365] (Jan 1 = 0) \(**/
|
|
int tm_isdst; /\(** daylight savings flag \(**/
|
|
long tm_gmtoff; /\(** offset from UTC in seconds \(**/
|
|
char \(**tm_zone; /\(** abbreviation of timezone name \(**/
|
|
.fi
|
|
.RE
|
|
.PP
|
|
The
|
|
.I tm_zone
|
|
and
|
|
.I tm_gmtoff
|
|
fields exist, and are filled in, only if arrangements to do
|
|
so were made when the library containing these functions was
|
|
created.
|
|
There is no guarantee that these fields will continue to exist
|
|
in this form in future releases of this code.
|
|
.PP
|
|
.I Tm_isdst\^
|
|
is non-zero if summer time is in effect.
|
|
.PP
|
|
.I Tm_gmtoff
|
|
is the offset (in seconds) of the time represented
|
|
from UTC, with positive values indicating east
|
|
of the Prime Meridian.
|
|
.SH FILES
|
|
.ta \w'/usr/share/zoneinfo/posixrules\0\0'u
|
|
/etc/localtime local time zone file
|
|
.br
|
|
/usr/share/zoneinfo time zone information directory
|
|
.br
|
|
/usr/share/zoneinfo/posixrules used with POSIX-style TZ's
|
|
.br
|
|
/usr/share/zoneinfo/GMT for UTC leap seconds
|
|
.sp
|
|
If
|
|
.B /usr/share/zoneinfo/GMT
|
|
is absent,
|
|
UTC leap seconds are loaded from
|
|
.BR /usr/share/zoneinfo/posixrules .
|
|
.SH SEE ALSO
|
|
getenv(3),
|
|
strftime(3),
|
|
tzset(3),
|
|
time(3),
|
|
tzfile(5)
|
|
.SH STANDARDS
|
|
The
|
|
ctime(),
|
|
difftime(),
|
|
asctime(),
|
|
localtime(),
|
|
gmtime()
|
|
and
|
|
mktime()
|
|
functions conform to
|
|
ANSI X3.159-1989 (``ANSI C'').
|
|
The
|
|
ctime_r(),
|
|
asctime_r(),
|
|
localtime_r()
|
|
and
|
|
gmtime_r()
|
|
functions conform to
|
|
IEEE Std1003.1c-1995 (``POSIX'').
|
|
.SH NOTES
|
|
The return values point to static data;
|
|
the data is overwritten by each call.
|
|
The
|
|
.B tm_zone
|
|
field of a returned
|
|
.B "struct tm"
|
|
points to a static array of characters, which
|
|
will also be overwritten at the next call
|
|
(and by calls to
|
|
.IR tzset ).
|
|
.PP
|
|
Avoid using out-of-range values with
|
|
.I mktime
|
|
when setting up lunch with promptness sticklers in Riyadh.
|
|
.\" @(#)newctime.3 7.14
|