CTIME(3) | Library Functions Manual | CTIME(3) |
asctime
, asctime_r
,
ctime
, ctime_r
,
ctime_rz
, difftime
,
gmtime
, gmtime_r
,
localtime
, localtime_r
,
localtime_rz
, mktime
,
mktime_z
—
#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);
asctime
family of functions provide various standard
library routines to operate with time and conversions related to time.
asctime
(tm)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)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)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)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)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)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 timezone to be used
for conversion. If zone is
NULL
, UT 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)gmtime
() function converts to Coordinated
Universal Time (UTC) and returns a pointer to the tm
structure described in
tm(3).gmtime_r
(clock,
result)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)localtime
() is comparable to
gmtime
(). However,
localtime
() corrects for the timezone and any
timezone 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 timezone abbreviation to be
used with localtime
()'s return value.localtime_r
(clock,
result)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)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)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.
mktime
()
to presume initially that daylight saving time respectively, is or is
not in effect for the specified time.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.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)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? */ 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) */
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.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.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.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.If /usr/share/zoneinfo/GMT is absent, UTC leap seconds are loaded from /usr/share/zoneinfo/posixrules.
EINVAL
]EOVERFLOW
]All functions that return values, except their “z” variants, can also return the same errors as open(2) and malloc(3).
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”).
ctime
() function appeared in
Version 1 AT&T UNIX.
tzname
variable
(once set) and the tm_zone field of a returned
struct tm point to an array of characters that can be
freed or overwritten by later calls to the functions
localtime
(), tzfree
(), and
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
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.
September 2, 2019 | NetBSD 9.2 |