252 lines
6.1 KiB
Groff
252 lines
6.1 KiB
Groff
.\" $NetBSD: ctime.3,v 1.24 2001/09/16 01:35:53 wiz Exp $
|
|
.Dd March 31, 2001
|
|
.Dt CTIME 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm asctime ,
|
|
.Nm asctime_r ,
|
|
.Nm ctime ,
|
|
.Nm ctime_r ,
|
|
.Nm difftime ,
|
|
.Nm gmtime ,
|
|
.Nm gmtime_r ,
|
|
.Nm localtime ,
|
|
.Nm localtime_r ,
|
|
.Nm mktime
|
|
.Nd convert date and time to ASCII
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include <time.h>
|
|
.Dv extern char *tzname[2];
|
|
.Ft char *
|
|
.Fn ctime "const time_t *clock"
|
|
.Ft char *
|
|
.Fn ctime_r "const time_t *clock" "char *buf"
|
|
.Ft double
|
|
.Fn difftime "time_t time1" "time_t time0"
|
|
.Ft char *
|
|
.Fn asctime "const struct tm *tm"
|
|
.Ft char *
|
|
.Fn asctime_r "const struct tm restrict tm" "char * restrict buf"
|
|
.Ft struct tm *
|
|
.Fn localtime "const time_t *clock"
|
|
.Ft struct tm *
|
|
.Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result"
|
|
.Ft struct tm *
|
|
.Fn gmtime "const time_t *clock"
|
|
.Ft struct tm *
|
|
.Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result"
|
|
.Ft time_t
|
|
.Fn mktime "struct tm *tm"
|
|
.Sh DESCRIPTION
|
|
.Fn ctime
|
|
converts a long integer, pointed to by
|
|
.Fa 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
|
|
.Dl Thu Nov 24 18:22:48 1986\en\e0
|
|
All the fields have constant width.
|
|
.Pp
|
|
The
|
|
.Fn ctime_r
|
|
function provides the same functionality as
|
|
.Fn ctime
|
|
differing in that the caller must supply a buffer area
|
|
.Fa buf
|
|
with a size of at least 26 bytes, in which the result is stored.
|
|
.Pp
|
|
.Fn localtime
|
|
and
|
|
.Fn gmtime
|
|
return pointers to
|
|
.Va tm
|
|
structures, described below.
|
|
.Fn 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
|
|
.Va tm
|
|
structure,
|
|
.Fn localtime
|
|
sets the
|
|
.Fa tm_isdst Ns 'th
|
|
element of
|
|
.Fa tzname
|
|
to a pointer to an
|
|
ASCII string that's the time zone abbreviation to be used with
|
|
.Fn localtime Ns 's
|
|
return value.
|
|
.Pp
|
|
.Fn gmtime
|
|
converts to Coordinated Universal Time.
|
|
.Pp
|
|
The
|
|
.Fn gmtime_r
|
|
and
|
|
.Fn localtime_r
|
|
functions provide the same functionality as
|
|
.Fn gmtime
|
|
and
|
|
.Fn localtime
|
|
differing in that the caller must supply a buffer area
|
|
.Fa result
|
|
in which the result is stored; also,
|
|
.Fn localtime_r
|
|
does not imply initialization of the local time conversion information;
|
|
the application may need to do so by calling
|
|
.Xr tzset 3 .
|
|
.Pp
|
|
.Fn asctime
|
|
converts a time value contained in a
|
|
.Va tm
|
|
structure to a 26-character string, as shown in the above example,
|
|
and returns a pointer to the string.
|
|
.Pp
|
|
The
|
|
.Fn asctime_r
|
|
function provides the same functionality as
|
|
.Fn asctime
|
|
differing in that the caller must supply a buffer area
|
|
.Fa buf
|
|
with a size of at least 26 bytes, in which the result is stored.
|
|
.Pp
|
|
.Fn mktime
|
|
converts the broken-down time, expressed as local time,
|
|
in the structure pointed to by
|
|
.Fa tm
|
|
into a calendar time value with the same encoding as that of the values
|
|
returned by the
|
|
.Xr time 3
|
|
function.
|
|
The original values of the
|
|
.Fa tm_wday
|
|
and
|
|
.Fa 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
|
|
.Fa tm_isdst
|
|
causes
|
|
.Fn 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
|
|
.Fa tm_isdst
|
|
causes the
|
|
.Fn mktime
|
|
function to attempt to divine whether summer time is in effect
|
|
for the specified time.)
|
|
On successful completion, the values of the
|
|
.Fa tm_wday
|
|
and
|
|
.Fa 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
|
|
.Fa tm_mday
|
|
is not set until
|
|
.Fa tm_mon
|
|
and
|
|
.Fa tm_year
|
|
are determined.
|
|
.Fn mktime
|
|
returns the specified calendar time; if the calendar time cannot be
|
|
represented, it returns -1.
|
|
.Pp
|
|
.Fn difftime
|
|
returns the difference between two calendar times,
|
|
.Fa ( time1 No - Fa time0 ) ,
|
|
expressed in seconds.
|
|
.Pp
|
|
The structure (of type)
|
|
.Va "struct tm"
|
|
includes the following fields:
|
|
.Bd -literal -offset indent
|
|
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 */
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fa tm_zone
|
|
and
|
|
.Fa 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
|
|
.Fa tm_isdst
|
|
is non-zero if summer time is in effect.
|
|
.Pp
|
|
.Fa tm_gmtoff
|
|
is the offset (in seconds) of the time represented
|
|
from UTC, with positive values indicating east
|
|
of the Prime Meridian.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/zoneinfo/posixrules -compact
|
|
.It Pa /etc/localtime
|
|
local time zone file
|
|
.It Pa /usr/share/zoneinfo
|
|
time zone information directory
|
|
.It Pa /usr/share/zoneinfo/posixrules
|
|
used with POSIX-style TZ's
|
|
.It Pa /usr/share/zoneinfo/GMT
|
|
for UTC leap seconds
|
|
.El
|
|
.Pp
|
|
If
|
|
.Pa /usr/share/zoneinfo/GMT
|
|
is absent, UTC leap seconds are loaded from
|
|
.Pa /usr/share/zoneinfo/posixrules .
|
|
.Sh SEE ALSO
|
|
.Xr getenv 3 ,
|
|
.Xr strftime 3 ,
|
|
.Xr time 3 ,
|
|
.Xr tzset 3 ,
|
|
.Xr tzfile 5
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn ctime ,
|
|
.Fn difftime ,
|
|
.Fn asctime ,
|
|
.Fn localtime ,
|
|
.Fn gmtime
|
|
and
|
|
.Fn mktime
|
|
functions conform to
|
|
.St -ansiC
|
|
The
|
|
.Fn ctime_r ,
|
|
.Fn asctime_r ,
|
|
.Fn localtime_r
|
|
and
|
|
.Fn gmtime_r
|
|
functions conform to
|
|
.St -p1003.1c-95 .
|
|
.Sh NOTES
|
|
The return values point to static data; the data is overwritten by
|
|
each call. The
|
|
.Fa tm_zone
|
|
field of a returned
|
|
.Va "struct tm"
|
|
points to a static array of characters, which will also be overwritten
|
|
at the next call (and by calls to
|
|
.Xr tzset 3 ) .
|
|
.Pp
|
|
Avoid using out-of-range values with
|
|
.Fn mktime
|
|
when setting up lunch with promptness sticklers in Riyadh.
|
|
.\" @(#)newctime.3 7.14
|