169 lines
7.9 KiB
Plaintext
169 lines
7.9 KiB
Plaintext
NEWCTIME(3) Library Functions Manual NEWCTIME(3)
|
|
|
|
NAME
|
|
asctime, ctime, difftime, gmtime, localtime, mktime - convert date and
|
|
time
|
|
|
|
SYNOPSIS
|
|
#include <time.h>
|
|
|
|
extern char *tzname[2];
|
|
|
|
char *ctime(time_t const *clock);
|
|
|
|
char *ctime_r(time_t const *clock, char *buf);
|
|
|
|
double difftime(time_t time1, time_t time0);
|
|
|
|
char *asctime(struct tm const *tm);
|
|
|
|
char *asctime_r(struct tm const *restrict tm,
|
|
char *restrict result);
|
|
|
|
struct tm *localtime(time_t const *clock);
|
|
|
|
struct tm *localtime_r(time_t const *restrict clock,
|
|
struct tm *restrict result);
|
|
|
|
struct tm *localtime_rz(timezone_t restrict zone,
|
|
time_t const *restrict clock,
|
|
struct tm *restrict result);
|
|
|
|
struct tm *gmtime(time_t const *clock);
|
|
|
|
struct tm *gmtime_r(time_t const *restrict clock,
|
|
struct tm *restrict result);
|
|
|
|
time_t mktime(struct tm *tm);
|
|
|
|
time_t mktime_z(timezone_t restrict zone,
|
|
struct tm *restrict tm);
|
|
|
|
cc ... -ltz
|
|
|
|
DESCRIPTION
|
|
Ctime converts a long integer, pointed to by clock, and returns a
|
|
pointer to a string of the form
|
|
Thu Nov 24 18:22:48 1986\n\0
|
|
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.
|
|
|
|
Localtime and gmtime return pointers to "tm" structures, described
|
|
below. Localtime corrects for the time zone and any time zone
|
|
adjustments (such as Daylight Saving Time in the United States). After
|
|
filling in the "tm" structure, localtime sets the tm_isdst'th element
|
|
of tzname to a pointer to a string that's the time zone abbreviation to
|
|
be used with localtime's return value.
|
|
|
|
Gmtime converts to Coordinated Universal Time.
|
|
|
|
Asctime converts a time value contained in a "tm" structure to a
|
|
string, as shown in the above example, and returns a pointer to the
|
|
string.
|
|
|
|
Mktime converts the broken-down time, expressed as local time, in the
|
|
structure pointed to by tm into a calendar time value with the same
|
|
encoding as that of the values returned by the time function. 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.
|
|
Mktime returns the specified calendar time; If the calendar time cannot
|
|
be represented, it returns -1.
|
|
|
|
Difftime returns the difference between two calendar times, (time1 -
|
|
time0), expressed in seconds.
|
|
|
|
Ctime_r, localtime_r, gmtime_r, and asctime_r are like their unsuffixed
|
|
counterparts, except that they accept an additional argument specifying
|
|
where to store the result if successful.
|
|
|
|
Localtime_rz and mktime_z 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 be 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.
|
|
|
|
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 time zone 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.
|
|
|
|
FILES
|
|
/usr/local/etc/zoneinfo time zone information directory
|
|
/usr/local/etc/zoneinfo/localtime local time zone file
|
|
/usr/local/etc/zoneinfo/posixrules used with POSIX-style TZ's
|
|
/usr/local/etc/zoneinfo/GMT for UTC leap seconds
|
|
|
|
If /usr/local/etc/zoneinfo/GMT is absent, UTC leap seconds are loaded
|
|
from /usr/local/etc/zoneinfo/posixrules.
|
|
|
|
SEE ALSO
|
|
getenv(3), newstrftime(3), newtzset(3), time(2), tzfile(5)
|
|
|
|
NOTES
|
|
The return values of asctime, ctime, gmtime, and localtime point to
|
|
static data overwritten by each call. The tm_zone field of a returned
|
|
struct tm points to a static array of characters, which can be
|
|
overwritten by later calls to tzset. The remaining functions and data
|
|
are thread-safe.
|
|
|
|
Asctime, asctime_r, ctime, and ctime_r 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.
|
|
|
|
NEWCTIME(3)
|