CTIME(3) CTIME(3)
NAME
asctime, asctime_r, ctime, ctime_r, difftime, gmtime, gmtime_r, localtime, localtime_r, mktime - convert date and time to ASCII
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <time.h> extern char *tzname[2]; char *ctime(const time_t *clock); char *ctime_r(const time_t *clock, char *buf); double difftime(time_t time1, time_t time0); char *asctime(const struct tm *tm); char *asctime_r(const struct tm *, char *buf); struct tm *localtime(const time_t *clock); struct tm *localtime_r(const time_t *clock, struct tm *result); struct tm *gmtime(const time_t *clock); struct tm *gmtime_r(const time_t *clock, struct tm *result); time_t mktime(struct tm *tm);
DESCRIPTION
Ctime converts a long integer, pointed to by clock, repre- senting the time in seconds since 00:00:00 UTC, 1970-01-01, and returns a pointer to a 26-character string of the form Thu Nov 24 18:22:48 1986\n\0 All the fields have constant width. The ctime_r function provides the same functionality as ctime differing in that the caller must supply a buffer area buf with a size of at least 26 bytes, in which the result is stored. 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 U.S.A.). After filling in the ``tm'' structure, localtime sets the tm_isdst'th element of tzname to a pointer to an ASCII string that's the time zone abbrevia- tion to be used with localtime's return value. Gmtime converts to Coordinated Universal Time. The gmtime_r and localtime_r functions provide the same 1 CTIME(3) CTIME(3) functionality as gmtime and localtime differing in that the caller must supply a buffer area result in which the result is stored; also, localtime_r does not imply ini- tialization of the local time conversion information; the application may need to do so by calling tzset. Asctime converts a time value contained in a ``tm'' struc- ture to a 26-character string, as shown in the above exam- ple, and returns a pointer to the string. The asctime_r function provides the same functionality as asctime differing in that the caller must supply a buffer area buf with a size of at least 26 bytes, in which the result is stored. 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.) On successful com- pletion, the values of the tm_wday and tm_yday components of the structure are set appropriately, and the other com- ponents 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. 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 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 (Sunday = 0) */ int tm_yday; /* day of year (0 - 365, 0 = Jan 1) */ int tm_isdst; /* is summer time in effect? */ 2 CTIME(3) CTIME(3) long tm_gmtoff; /* offset from UTC in seconds */ char *tm_zone; /* abbreviation of timezone name */ 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 guar- antee 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 repre- sented from UTC, with positive values indicating east of the Prime Meridian.
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.
SEE ALSO
getenv(3), strftime(3), tzset(3), time(3), tzfile(5)
STANDARDS
The ctime(), difftime(), asctime(), localtime(), gmtime() and mktime() functions conform to ANSI X3.159-1989 (``ANSI C''). The ctime_r(), asctime_r(), localtime_r() and gmtime_r() functions conform to IEEE Std1003.1c-1995 (``POSIX'').
NOTES
The return values point to static data; the data is over- written by each call. 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). Avoid using out-of-range values with mktime when setting up lunch with promptness sticklers in Riyadh. 3
Powered by man-cgi (2024-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.