NAME
asctime,
asctime_r,
ctime,
ctime_r,
ctime_rz,
difftime,
gmtime,
gmtime_r,
localtime,
localtime_r,
localtime_rz,
mktime,
mktime_z —
convert date and time
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <time.h>
extern char *tzname[2];
char *
asctime(
const
struct tm *tm);
char *
asctime_r(
const
struct tm *restrict tm,
char * restrict buf);
char *
ctime(
const
time_t *clock);
char *
ctime_r(
const
time_t *clock,
char
*buf);
char *
ctime_rz(
timezone_t
restrict tz,
const time_t
*clock,
char *buf);
double
difftime(
time_t
time1,
time_t time0);
struct tm *
gmtime(
const
time_t *clock);
struct tm *
gmtime_r(
const
time_t * restrict clock,
struct tm * restrict
result);
struct tm *
localtime(
const
time_t *clock);
struct tm *
localtime_r(
const
time_t * restrict clock,
struct tm * restrict
result);
struct tm *
localtime_rz(
timezone_t
restrict tz,
const time_t *
restrict clock,
struct tm *
restrict result);
time_t
mktime(
struct tm
*tm);
time_t
mktime_z(
timezone_t
restrict tz,
struct tm
*restrict tm);
DESCRIPTION
The
asctime family of functions provide various standard
library routines to operate with time and conversions related to time.
FUNCTIONS
-
-
- asctime(tm)
- The asctime() function converts a time
value contained in the tm structure to a string with
the following general format:
Thu Nov 24 18:22:48 1986\n\0
The tm structure is described in
tm(3).
-
-
- asctime_r(tm,
buf)
- The asctime_r() has the same behavior as
asctime(), but the result is stored in
buf, which should have a size of at least 26
bytes.
-
-
- ctime(clock)
- The ctime() function converts a
time_t, pointed to by 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
Thu Nov 24 18:22:48 81986\n\0
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.
The 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.
-
-
- ctime_r(clock,
buf)
- The ctime_r() is similar to
ctime(), except it places the result of the conversion
in the buf argument, which should be 26 or more
bytes long, instead of using a global static buffer.
-
-
- ctime_rz(tz,
clock, buf)
- The ctime_rz() function is similar to
ctime_r(), but it also takes a
timezone_t argument, as returned by a previous call
to tzalloc(), or a
NULL
pointer
denoting Coordinated Universal Time (UTC).
-
-
- difftime(time1,
time2)
- The difftime() function returns the
difference between two calendar times, (time1
- time0), expressed in
seconds.
The ctime_r(), localtime_r(),
gmtime_r(), and asctime_r() functions
are like their unsuffixed counterparts, except that they accept an
additional argument specifying where to store the result if successful.
The ctime_rz(), localtime_rz(), and
mktime_z() functions are like their unsuffixed
counterparts, except that they accept an extra initial
zone argument specifying the time zone to be used
for conversion. If zone is
NULL
, UTC is used; otherwise,
zone should have been allocated by
tzalloc() and should not be freed until after all uses
(e.g., by calls to strftime()) of the filled-in
tm_zone() fields.
-
-
- gmtime(clock)
- The gmtime() function converts to
Coordinated Universal Time (UTC) and returns a pointer to the
tm structure described in
tm(3).
-
-
- gmtime_r(clock,
result)
- The gmtime_r() function provides the same
functionality as gmtime(), differing in that the caller
must supply a buffer area result in which the result
is stored.
-
-
- localtime(clock)
- Also localtime() is comparable to
gmtime(). However, 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, the function sets the tm_isdst'th element
of tzname to a pointer to an ASCII string that is
the time zone abbreviation to be used with localtime()'s
return value.
-
-
- localtime_r(clock,
result)
- As gmtime_r(), the
localtime_r() takes an additional buffer
result as a parameter and stores the result in it.
Note however that localtime_r() does not imply
initialization of the local time conversion information; the application
may need to do so by calling
tzset(3).
-
-
- localtime_rz(tz,
clock, result)
- The localtime_rz() function is similar to
localtime_r(), but it also takes a
timezone_t argument, returned by a previous call to
tzalloc(), or a
NULL
pointer
denoting Coordinated Universal Time (UTC).
-
-
- mktime(tm)
- The mktime() function converts the
broken-down time, expressed as local time in the
tm(3) structure, into a calendar
time value with the same encoding as that of the values returned by the
time(3) function. The
following remarks should be taken into account.
- The original values of the
tm_wday and 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 tm_isdst causes
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 tm_isdst
causes the mktime() function to attempt to divine
whether summer 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.
- On successful completion, the values of the
tm_wday and 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
tm_mday is not set until
tm_mon and tm_year are
determined.
The function returns the specified calendar time; if the calendar time
cannot be represented, it returns (time_t)-1. This
can happen either because the resulting conversion would not fit in a
time_t variable, or because the time specified
happens to be in the daylight savings gap and
tm_isdst was set to -1
.
Other 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.
-
-
- mktime_z(tz,
tm)
- The mktime_z() function is similar to
mktime() but it also takes a const
timezone_t argument, returned by a previous call to
tzalloc(), or a null pointer denoting Coordinated
Universal Time (UTC).
Declarations of all the functions and externals, and the
tm structure, are in the
<time.h> header file. The structure
(of type)
struct tm includes the following fields:
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? */
char *tm_zone; /* abbreviation of timezone name */
long tm_gmtoff; /* offset from UT in seconds */
The
tm_zone and
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.
- tm_isdst is non-zero if summer
time is in effect.
- 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.
RETURN VALUES
- On success the asctime() and
ctime() functions return a pointer to a static character
buffer, and the asctime_r(),
ctime_r(), and ctime_rz() function
return a pointer to the user-supplied buffer. On failure they all return
NULL
and no errors are defined for them.
- On success the gmtime(), and
localtime() functions return a pointer to a statically
allocated struct tm whereas the
gmtime_r(), localtime_r(), and
localtime_rz(), functions return a pointer to the
user-supplied struct tm. On failure they all return
NULL
and the global variable
errno is set to indicate the error.
- The mktime() and
mktime_z() function returns the specified time since the
Epoch as a time_t type value. If the time cannot be
represented, then mktime() and
mktime_z() return (time_t)-1
setting the global variable errno to indicate the
error.
- The tzalloc() function returns a
pointer to a timezone_t object or
NULL
on failure, setting
errno to indicate the error. It may also return
NULL
when the name argument
is NULL
, and this is not an error, but a way of
referring to Coordinated Universal Time (UTC).
- tzgetzone() function returns string
containing the name of the timezone given in
tz.
FILES
- /etc/localtime
- local time zone file
- /usr/share/zoneinfo
- time zone information directory
- /usr/share/zoneinfo/posixrules
- used with POSIX-style TZ's
- /usr/share/zoneinfo/GMT
- for UTC leap seconds
If
/usr/share/zoneinfo/GMT is absent, UTC leap seconds are
loaded from
/usr/share/zoneinfo/posixrules.
ERRORS
The described functions may fail with
-
-
- [
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).
-
-
- [
EOVERFLOW
]
- The result cannot be represented because the time requested
is out of bounds and the time calculation resulted in overflow.
All functions that return values, except their “z” variants, can
also return the same errors as
open(2) and
malloc(3).
SEE ALSO
getenv(3),
strftime(3),
time(3),
tm(3),
tzset(3),
tzfile(5)
STANDARDS
The
ctime(),
difftime(),
asctime(),
localtime(),
gmtime() and
mktime() functions conform to
ANSI X3.159-1989 (“ANSI C89”). Rest
of the functions conform to
IEEE Std 1003.1-2008
(“POSIX.1”).
CAVEATS
The functions that do not take an explicit
timezone_t
argument return values pointing to static data; the data is overwritten by
each call. For the above functions the
tm_zone field of
a returned
struct tm points to a static array of
characters, which will also be overwritten at the next call (and by calls to
tzset(3)). The functions that do
take an explicit
timezone_t argument and set the fields
of a supplied
struct tm should not call
tzfree() since the
tm_zone field of
the
struct tm points to data allocated by
tzalloc().
The
asctime(),
asctime_r(),
ctime(),
ctime_r(), and
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
strftime() instead.