*** UNIX MANUAL PAGE BROWSER ***

ctime(3) Library Functions Manual ctime(3) NAME asctime, asctime_r, ctime, ctime_r, gmtime, gmtime_r, localtime, local- time_r, mktime - Converts time units LIBRARY Standard C Library: (libc.so, libc.a) SYNOPSIS #include <time.h> char *asctime( const struct tm *timeptr) ; char *asctime_r( const struct tm *timeptr, char *buffer) ; char *ctime( const time_t *timer) ; char *ctime_r( const time_t *timer, char *buffer) ; struct tm *gmtime( const time_t *timer) ; struct tm *gmtime_r( const time_t *timer, struct tm *result) ; struct tm *localtime( const time_t *timer ) ; struct tm *localtime_r( const time_t *timer, struct tm *result) ; time_t mktime( struct tm *timeptr) ; [Digital] The following functions are supported in order to maintain backward compatibility with previous versions of the operating system. You should not use them in new designs. int asctime_r( const struct tm *timeptr, char *buffer, int len) ; int ctime_r( const time_t *timer, char *buffer, int len) ; int gmtime_r( const time_t *timer, struct tm *result) ; int localtime_r( const time_t *timer, struct tm *result) ; STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: asctime_r(), ctime_r(), gmtime_r(), localtime_r(): POSIX.1c asctime(), ctime(), gmtime(), localtime(), mktime(): XPG4, XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Points to a type tm structure that defines space for a broken-down time value. Points to a variable that specifies a time value in seconds. Points to a character array that is at least 26 bytes long. This array is used to store the generated date and time string. Specifies an in- teger that defines the length of the character array. DESCRIPTION The asctime, ctime, gmtime, localtime, mktime, and tzset functions con- vert time values between tm structures, time_t type variables, and strings. [POSIX] The asctime_r, ctime_r, gmtime_r, and localtime_r functions in libc_r.a are threadsafe because they do not return pointers to static data. The tm structure, which is defined in the <time.h> header file, con- tains the following elements: tab(@); l lw(3.25i) . inttm_sec@Seconds after the minute [0-60] inttm_min@Minutes after the hour [0-59] inttm_hour@Hours since midnight [0-23] inttm_mday@Day of the month [1-31] inttm_mon@Months since January [0-11] inttm_year@Years since 1900 inttm_wday@Days since Sunday [0-6] inttm_yday@Days since January 1 [0-365] inttm_isdst@Daylight Saving Time flag longtm_gmtoff@Seconds east of Greenwich. (Negative values indicate @seconds west of Greenwich.) char*tm_zone@Timezone string, for example, GMT _ A time_t variable, also defined in <time.h>, contains the number of seconds since the Epoch, 00:00:00 UTC 1 Jan 1970. A string used to represent a time value has a five-field format. For example: Tue Nov 9 15:37:29 1993\n\0 The asctime function converts the tm structure pointed to by the timeptr parameter to a string with this five-field format. The func- tion uses the following members of the tm structure: tm_wday tm_mon tm_mday tm_hour tm_min tm_sec tm_year The ctime function converts the time_t variable pointed to by the timer parameter to a string with the five-field format. Local timezone in- formation is set as though the tzset function had been called. This function is equivalent to asctime(localtime(timer)). The gmtime function converts the time_t variable pointed to by the timer parameter to a tm structure, expressed as GMT (Greenwich Mean Time). The localtime function converts the time_t variable pointed to by the timer parameter to a tm structure, expressed as local time. This func- tion corrects for the local timezone and any seasonal time adjustments. Local timezone information is set as if the tzset function had been called. The mktime function converts the tm structure pointed to by the timeptr parameter to a time_t variable. The function uses the following mem- bers of the tm structure: tm_year tm_mon tm_mday tm_hour tm_min tm_sec tm_isdst The values of these members are not restricted to the ranges defined in <time.h>. The range for tm_sec is increased to [0-61] to allow for an occasional leap second or double leap second. A positive value for tm_isdst tells the mktime function that Daylight Saving Time is in effect. A zero (0) value indicates that Standard Time is in effect. A negative values directs the mktime function to determine whether Daylight Saving Time is in effect for the specified time. Local timezone information is set as if the tzset function had been called. On successful completion of the call, values for the timeptr->tm_wday and timeptr->tm_yday members of the structure are set. The other mem- bers are set to specified times, but have their values forced to the ranges indicated previously. The final timeptr->tm_mday is not set un- til the values of the members timeptr->tm_mon and timeptr->tm_year are determined. If member tm_isdst is given as a negative number, it is set to 0 or 1 by mktime, depending on whether Daylight Saving Time is in effect at the specified time. NOTES The asctime, ctime, gmtime, and localtime functions are not supported for multithreaded applications. [POSIX] Instead, their reentrant equivalents, asctime_r, ctime_r, gm- time_r, and localtime_r, should be used with multiple threads. RETURN VALUES When any of the asctime, ctime, gmtime, or localtime functions complete successfully, the return value may point to static storage, which may be overwritten by subsequent calls to these functions. On error, these functions return a null pointer and errno is set to a value indicating the error. Upon successful completion, the asctime, asctime_r, ctime, and ctime_r functions return a pointer to a character string that expresses the time in a fixed format. Upon successful completion, the gmtime and gmtime_r functions return a pointer to a tm structure containing converted GMT time information. Upon successful completion, the localtime and localtime_r functions re- turn a pointer to a tm structure containing converted local time. Upon successful completion, the mktime function returns the specified time since the Epoch as a value of type time_t. If the time since the Epoch cannot be represented, mktime returns the value (time_t)-1 to in- dicate the error. [Digital] In addition to returning (time_t)-1 when the time since the Epoch cannot be represented, the mktime function also sets errno to the value ERANGE. This extension is provided to support times prior to the Epoch (that is, negative time_t values); in which case, the value (time_t)-1 may also correspond to the time 23:59:59 UTC 31 December 1969 (one second before the Epoch). For applications supporting pre- Epoch times, it is therefore necessary to check both the return value and the value of errno to reliably determine whether an error occurred. Note that this extension is not a standard feature and may not be portable to other UNIX platforms. [Digital] Upon successful completion, the obsolete versions of the as- ctime_r, ctime_r, gmtime_r, and localtime_r, functions return a value of 0 (zero). Otherwise, -1 is returned and errno is set to indicate the error. ERRORS With the exception of mktime(), if any of these functions fails, errno may be set to the following value: [Digital] The buffer, timer, or timeptr parameter is null, the len parameter is less than 1. If mktime() is not able to represent the time since the Epoch, it re- turns the value (time_t)-1 and sets errno to the following value: [Dig- ital] The time since the Epoch cannot be represented by mktime. RELATED INFORMATION Functions: difftime(3), getenv(3), strftime(3), time(3), timezone(3) Standards: standards(5) delim off ctime(3)