552 lines
13 KiB
Groff
552 lines
13 KiB
Groff
.\" $NetBSD: ctime.3,v 1.60 2018/10/19 23:05:35 christos Exp $
|
|
.\"
|
|
.\" XXX: License missing?
|
|
.\"
|
|
.Dd May 5, 2018
|
|
.Dt CTIME 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm asctime ,
|
|
.Nm asctime_r ,
|
|
.Nm ctime ,
|
|
.Nm ctime_r ,
|
|
.Nm ctime_rz ,
|
|
.Nm difftime ,
|
|
.Nm gmtime ,
|
|
.Nm gmtime_r ,
|
|
.Nm localtime ,
|
|
.Nm localtime_r ,
|
|
.Nm localtime_rz ,
|
|
.Nm mktime ,
|
|
.Nm mktime_z
|
|
.Nd convert date and time
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In time.h
|
|
.Vt extern char *tzname[2];
|
|
.Ft char *
|
|
.Fn asctime "const struct tm *tm"
|
|
.Ft char *
|
|
.Fn asctime_r "const struct tm *restrict tm" "char * restrict buf"
|
|
.Ft char *
|
|
.Fn ctime "const time_t *clock"
|
|
.Ft char *
|
|
.Fn ctime_r "const time_t *clock" "char *buf"
|
|
.Ft char *
|
|
.Fn ctime_rz "timezone_t restrict tz" "const time_t *clock" "char *buf"
|
|
.Ft double
|
|
.Fn difftime "time_t time1" "time_t time0"
|
|
.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 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 localtime_rz "timezone_t restrict tz" "const time_t * restrict clock" "struct tm * restrict result"
|
|
.Ft time_t
|
|
.Fn mktime "struct tm *tm"
|
|
.Ft time_t
|
|
.Fn mktime_z "timezone_t restrict tz" "struct tm *restrict tm"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
family of functions provide various standard library routines
|
|
to operate with time and conversions related to time.
|
|
.Sh FUNCTIONS
|
|
.Bl -tag -width abcd
|
|
.It Fn asctime "tm"
|
|
The
|
|
.Fn asctime
|
|
function converts a time value contained in the
|
|
.Fa tm
|
|
structure to a string with the following general format:
|
|
.Bd -literal -offset indent
|
|
Thu Nov 24 18:22:48 1986\en\e0
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Fa tm
|
|
structure is described in
|
|
.Xr tm 3 .
|
|
.It Fn asctime_r "tm" "buf"
|
|
The
|
|
.Fn asctime_r
|
|
has the same behavior as
|
|
.Fn asctime ,
|
|
but the result is stored in
|
|
.Fa buf ,
|
|
which should have a size of at least 26 bytes.
|
|
.It Fn ctime "clock"
|
|
The
|
|
.Fn ctime
|
|
function converts a
|
|
.Vt time_t ,
|
|
pointed to by
|
|
.Fa clock ,
|
|
and returns a pointer to a string with the format described above.
|
|
Years requiring fewer than four characters are padded with leading zeroes.
|
|
For years longer than four characters, the string is of the form
|
|
.Bd -literal -offset indent
|
|
Thu Nov 24 18:22:48 81986\en\e0
|
|
.Ed
|
|
.Pp
|
|
with five spaces before the year.
|
|
These unusual formats are designed to make it less likely that older
|
|
software that expects exactly 26 bytes of output will mistakenly output
|
|
misleading values for out-of-range years.
|
|
.Pp
|
|
The
|
|
.Fa clock
|
|
time stamp represents the time in seconds since 1970-01-01 00:00:00
|
|
Coordinated Universal Time (UTC).
|
|
The POSIX standard says that time stamps must be nonnegative
|
|
and must ignore leap seconds.
|
|
Many implementations extend POSIX by allowing negative time stamps,
|
|
and can therefore represent time stamps that predate the
|
|
introduction of UTC and are some other flavor of Universal Time (UT).
|
|
Some implementations support leap seconds, in contradiction to POSIX.
|
|
.It Fn ctime_r "clock" "buf"
|
|
The
|
|
.Fn ctime_r
|
|
is similar to
|
|
.Fn ctime ,
|
|
except it places the result of the conversion in the
|
|
.Fa buf
|
|
argument, which should be 26 or more bytes long,
|
|
instead of using a global static buffer.
|
|
.It Fn ctime_rz "tz" "clock" "buf"
|
|
The
|
|
.Fn ctime_rz
|
|
function is similar to
|
|
.Fn ctime_r ,
|
|
but it also takes a
|
|
.Ft "timezone_t"
|
|
argument, as returned by a previous call to
|
|
.Fn tzalloc ,
|
|
or a
|
|
.Dv NULL
|
|
pointer denoting
|
|
Coordinated Universal Time
|
|
.Pq UTC .
|
|
.It Fn difftime "time1" "time2"
|
|
The
|
|
.Fn difftime
|
|
function returns the difference between two calendar times,
|
|
.Fa ( time1 No - Fa time0 ) ,
|
|
expressed in seconds.
|
|
.Pp
|
|
The
|
|
.Fn ctime_r ,
|
|
.Fn localtime_r ,
|
|
.Fn gmtime_r ,
|
|
and
|
|
.Fn asctime_r
|
|
functions
|
|
are like their unsuffixed counterparts, except that they accept an
|
|
additional argument specifying where to store the result if successful.
|
|
.Pp
|
|
The
|
|
.Fn ctime_rz ,
|
|
.Fn localtime_rz ,
|
|
and
|
|
.Fn mktime_z
|
|
functions
|
|
are like their unsuffixed counterparts, except that they accept an
|
|
extra initial
|
|
.Ar zone
|
|
argument specifying the timezone to be used for conversion.
|
|
If
|
|
.Fa zone
|
|
is
|
|
.Dv NULL ,
|
|
UT is used; otherwise,
|
|
.Fa zone
|
|
should have been allocated by
|
|
.Fn tzalloc
|
|
and should not be freed until after all uses (e.g., by calls to
|
|
.Fn strftime )
|
|
of the filled-in
|
|
.Fn tm_zone
|
|
fields.
|
|
.It Fn gmtime "clock"
|
|
The
|
|
.Fn gmtime
|
|
function converts to Coordinated Universal Time
|
|
.Pq UTC
|
|
and returns a pointer to the
|
|
.Va tm
|
|
structure described in
|
|
.Xr tm 3 .
|
|
.It Fn gmtime_r "clock" "result"
|
|
The
|
|
.Fn gmtime_r
|
|
function provides the same functionality as
|
|
.Fn gmtime ,
|
|
differing in that the caller must supply a buffer area
|
|
.Fa result
|
|
in which the result is stored.
|
|
.It Fn localtime "clock"
|
|
Also
|
|
.Fn localtime
|
|
is comparable to
|
|
.Fn gmtime .
|
|
However,
|
|
.Fn localtime
|
|
corrects for the timezone and any timezone adjustments
|
|
(such as Daylight Saving Time in the U.S.A.).
|
|
After filling in the
|
|
.Va tm
|
|
structure, the function sets the
|
|
.Fa tm_isdst Ns 'th
|
|
element of
|
|
.Fa tzname
|
|
to a pointer to an
|
|
ASCII string that is the timezone abbreviation to be used with
|
|
.Fn localtime Ns 's
|
|
return value.
|
|
.It Fn localtime_r "clock" "result"
|
|
As
|
|
.Fn gmtime_r ,
|
|
the
|
|
.Fn localtime_r
|
|
takes an additional buffer
|
|
.Fa result
|
|
as a parameter and stores the result in it.
|
|
Note however that
|
|
.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 .
|
|
.It Fn localtime_rz "tz" "clock" "result"
|
|
The
|
|
.Fn localtime_rz
|
|
function is similar to
|
|
.Fn localtime_r ,
|
|
but it also takes a
|
|
.Ft "timezone_t"
|
|
argument, returned by a previous call to
|
|
.Fn tzalloc ,
|
|
or a
|
|
.Dv NULL
|
|
pointer denoting Coordinated Universal Time
|
|
.Pq UTC .
|
|
.It Fn mktime "tm"
|
|
The
|
|
.Fn mktime
|
|
function converts the broken-down time,
|
|
expressed as local time in the
|
|
.Xr tm 3
|
|
structure, into a calendar time value with
|
|
the same encoding as that of the values returned by the
|
|
.Xr time 3
|
|
function.
|
|
The following remarks should be taken into account.
|
|
.Bl -bullet
|
|
.It
|
|
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 daylight saving time
|
|
respectively,
|
|
is or is not in effect for the specified time.
|
|
.It
|
|
A negative value for
|
|
.Fa tm_isdst
|
|
causes the
|
|
.Fn mktime
|
|
function to attempt to divine whether daylight saving time is in effect
|
|
for the specified time; in this case it does not use a consistent
|
|
rule and may give a different answer when later
|
|
presented with the same argument.
|
|
.It
|
|
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.
|
|
.El
|
|
.Pp
|
|
The function returns the specified calendar time;
|
|
if the calendar time cannot be represented, it returns
|
|
.Va "(time_t)-1" .
|
|
This can happen either because the resulting conversion would not fit
|
|
in a
|
|
.Vt time_t
|
|
variable, or because the time specified happens to be in the daylight
|
|
savings gap and
|
|
.Fa tm_isdst
|
|
was set to
|
|
.Dv \-1 .
|
|
Other
|
|
.Fn mktime
|
|
implementations do not return an error in the second case and return
|
|
the appropriate time offset after the daylight savings gap.
|
|
There is code to mimick this behavior, but it is not enabled by default.
|
|
.It Fn mktime_z "tz" "tm"
|
|
The
|
|
.Fn mktime_z
|
|
function is similar to
|
|
.Fn mktime
|
|
but it also takes a
|
|
.Ft "const timezone_t"
|
|
argument, returned by a previous call to
|
|
.Fn tzalloc ,
|
|
or a null pointer denoting
|
|
Coordinated Universal Time
|
|
.Pq UTC .
|
|
.El
|
|
.Pp
|
|
Declarations of all the functions and externals, and the
|
|
.Ft tm
|
|
structure, are in the
|
|
.In time.h
|
|
header file.
|
|
The structure (of type)
|
|
.Ft struct tm
|
|
includes the following fields:
|
|
.Bd -literal
|
|
int tm_sec; /* seconds (0 - 60) */
|
|
int tm_min; /* minutes (0 - 59) */
|
|
int tm_hour; /* hours (0 - 23) */
|
|
int tm_mday; /* day of month (1 - 31) */
|
|
int tm_mon; /* month of year (0 - 11) */
|
|
int tm_year; /* year - 1900 */
|
|
int tm_wday; /* day of week (Sunday = 0) */
|
|
int tm_yday; /* day of year (0 - 365) */
|
|
int tm_isdst; /* is summer time in effect? */
|
|
int tm_isdst; /* is daylight saving time in effect? */
|
|
char *tm_zone; /* abbreviation of timezone name (optional) */
|
|
long tm_gmtoff; /* offset from UT in seconds (optional) */
|
|
.Ed
|
|
.Bl -bullet
|
|
.It
|
|
.Va tm_isdst
|
|
is non-zero if daylight saving time is in effect.
|
|
.It
|
|
.Va tm_gmtoff
|
|
is the offset (in seconds) of the time represented from UT,
|
|
with positive values indicating east of the Prime Meridian.
|
|
The field's name is derived from Greenwich Mean Time, a precursor of UT.
|
|
.El
|
|
In
|
|
.Ft struct tm
|
|
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.
|
|
Similarly, the
|
|
.Va tzname
|
|
variable is optional.
|
|
There is no guarantee that these fields and this variable will
|
|
continue to exist in this form in future releases of this code.
|
|
.Sh RETURN VALUES
|
|
.Bl -bullet
|
|
.It
|
|
On success the
|
|
.Fn asctime
|
|
and
|
|
.Fn ctime
|
|
functions return a pointer to a static character buffer, and the
|
|
.Fn asctime_r ,
|
|
.Fn ctime_r ,
|
|
and
|
|
.Fn ctime_rz
|
|
function return a pointer to the user-supplied buffer.
|
|
On failure they all return
|
|
.Dv NULL
|
|
and no errors are defined for them.
|
|
.It
|
|
On success the
|
|
.Fn gmtime ,
|
|
and
|
|
.Fn localtime
|
|
functions return a pointer to a statically allocated
|
|
.Va "struct tm"
|
|
whereas the
|
|
.Fn gmtime_r ,
|
|
.Fn localtime_r ,
|
|
and
|
|
.Fn localtime_rz ,
|
|
functions return a pointer to the user-supplied
|
|
.Va "struct tm" .
|
|
On failure they all return
|
|
.Dv NULL
|
|
and the global variable
|
|
.Va errno
|
|
is set to indicate the error.
|
|
.It
|
|
The
|
|
.Fn mktime
|
|
and
|
|
.Fn mktime_z
|
|
function returns the specified time since the Epoch as a
|
|
.Vt time_t
|
|
type value.
|
|
If the time cannot be represented, then
|
|
.Fn mktime
|
|
and
|
|
.Fn mktime_z
|
|
return
|
|
.Va "(time_t)-1"
|
|
setting the global variable
|
|
.Va errno
|
|
to indicate the error.
|
|
.It
|
|
The
|
|
.Fn tzalloc
|
|
function returns a pointer to a
|
|
.Ft timezone_t
|
|
object or
|
|
.Dv NULL
|
|
on failure, setting
|
|
.Va errno
|
|
to indicate the error.
|
|
It may also return
|
|
.Dv NULL
|
|
when the
|
|
.Fa name
|
|
argument is
|
|
.Dv NULL ,
|
|
and this is not an error, but a way of referring to
|
|
Coordinated Universal Time
|
|
.Pq UTC .
|
|
.It
|
|
.Fn tzgetzone
|
|
function returns string containing the name of the timezone given in
|
|
.Fa tz .
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/zoneinfo/posixrules -compact
|
|
.It Pa /etc/localtime
|
|
local timezone file
|
|
.It Pa /usr/share/zoneinfo
|
|
timezone information directory
|
|
.It Pa usr/share/zoneinfo/localtime
|
|
local timezone file
|
|
.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 ERRORS
|
|
The described functions may fail with
|
|
.Bl -tag -width Er
|
|
.It Bq Er EINVAL
|
|
The result cannot be represented because a parameter is incorrect, or
|
|
the conversion failed because no such time exists (for example a time
|
|
in the DST gap).
|
|
.It Bq Er EOVERFLOW
|
|
The result cannot be represented because the time requested is out of bounds
|
|
and the time calculation resulted in overflow.
|
|
.El
|
|
.Pp
|
|
All functions that return values, except their
|
|
.Dq z
|
|
variants, can also return the same errors as
|
|
.Xr open 2
|
|
and
|
|
.Xr malloc 3 .
|
|
.Sh SEE ALSO
|
|
.Xr getenv 3 ,
|
|
.Xr strftime 3 ,
|
|
.Xr time 3 ,
|
|
.Xr tm 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 .
|
|
Rest of the functions conform to
|
|
.St -p1003.1-2008 .
|
|
.Sh CAVEATS
|
|
The functions that do not take an explicit
|
|
.Ft timezone_t
|
|
argument return values pointing to static data; the data is overwritten by
|
|
each call.
|
|
For the above functions the
|
|
.Dv tzname
|
|
variable (once set) and the
|
|
.Fa tm_zone
|
|
field of a returned
|
|
.Va "struct tm"
|
|
point to an array of characters that
|
|
can be freed or overwritten by later calls to the functions
|
|
.Fn localtime ,
|
|
.Fn tzfree ,
|
|
and
|
|
.Fn tzset ,
|
|
if these functions affect the timezone information that specifies the
|
|
abbreviation in question.
|
|
The remaining functions and data are thread-safe.
|
|
The functions that do take an explicit
|
|
.Ft timezone_t
|
|
argument and set the fields of a supplied
|
|
.Va "struct tm"
|
|
should not call
|
|
.Fn tzfree
|
|
since the
|
|
.Fa tm_zone
|
|
field of the
|
|
.Va "struct tm"
|
|
points to data allocated by
|
|
.Fn tzalloc .
|
|
.Pp
|
|
The
|
|
.Fn asctime ,
|
|
.Fn asctime_r ,
|
|
.Fn ctime ,
|
|
.Fn ctime_r ,
|
|
and
|
|
.Fn ctime_rz ,
|
|
functions behave strangely for years before 1000 or after 9999.
|
|
The 1989 and 1999 editions of the C Standard say
|
|
that years from \-99 through 999 are converted without
|
|
extra spaces, but this conflicts with longstanding
|
|
tradition and with this implementation.
|
|
The 2011 edition says that the behavior
|
|
is undefined if the year is before 1000 or after 9999.
|
|
Traditional implementations of these two functions are
|
|
restricted to years in the range 1900 through 2099.
|
|
To avoid this portability mess, new programs should use
|
|
.Fn strftime
|
|
instead.
|
|
.\" @(#)newctime.3 8.3
|
|
.\" This file is in the public domain, so clarified as of
|
|
.\" 2009-05-17 by Arthur David Olson.
|