NAME

asctime, asctime_r, ctime, ctime_r, gmtime, gmtime_r, localtime, localtime_r, mktime - Converts time units

LIBRARY

Standard C Libraries: (libc.a; libc_r.a)

SYNOPSIS

#include <time.h>

char ∗asctime(
    const struct tm ∗timeptr) ;

int asctime_r(
    const struct tm ∗timeptr,
    char ∗buffer,
    int len) ;

char ∗ctime(
    const time_t ∗timer) ;

int ctime_r(
    const time_t ∗timer,
    char ∗buffer,
    int len ) ;

struct tm ∗gmtime(
    const time_t ∗timer) ;

int gmtime_r(
    const time_t ∗timer,
    struct tm ∗result) ;

struct tm ∗localtime(
    const time_t ∗timer ) ;

int localtime_r(
    const time_t ∗timer,
    struct tm ∗result) ;

time_t mktime(
    struct tm ∗timeptr) ;

PARAMETERS

timeptrPoints to a type tm structure that defines space for a broken-down time value. 

timerPoints to a variable that specifies a time value in seconds. 

bufferPoints to a character array used to store the generated date and time string. 

lenSpecifies an integer that defines the length of the character array. 

DESCRIPTION

The asctime(), ctime(), gmtime(), localtime(), mktime(), and tzset() functions convert time values between tm structures, time_t type variables, and strings. 

The asctime_r(), ctime_r(), gmtime_r(), and localtime_r() functions in libc_r.a are thread-safe versions of the corresponding functions in libc.a.  These functions are thread-safe because they do not return pointers to static data. 

The tm structure, which is defined in <time.h>, contains the following elements:

A time_t variable, also defined in <time.h>, contains the number of seconds since the Epoch, 00:00:00 GMT 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 function uses the following members of the tm structure:

tm_wday
tm_mon
tm_mday
tm_hour
tm_min
tm_sec
tm_year

The asctime_r() function is the reentrant version of asctime() for use with multiple threads. 

The ctime() function converts the time_t variable pointed to by the timer parameter to a string with the five-field format.  Local timezone information is set as though the tzset() function had been called.  This function is equivalent to asctime(localtime(timer)). 

The ctime_r() function is the reentrant version of ctime() for use with multiple threads. 

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 gmtime_r() function is the reentrant version of gmtime() for use with multiple threads. 

The localtime() function converts the time_t variable pointed to by the timer parameter to a tm structure, expressed as local time.  This function corrects for the local timezone and any seasonal time adjustments.  Local timezone information is set as if the tzset() function had been called. 

The localtime_r() function is the reentrant version of localtime() for use with multiple threads. 

The mktime() function converts the tm structure pointed to by the timeptr parameter to a time_t variable.  The function uses the following members 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 requests that the mktime() function find out 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 members are set to specified times, but have their values forced to the ranges indicated previously.  The final timeptr->tm_mday is not set until 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 multi-threaded applications.  Instead, their reentrant equivalents, asctime_r(), ctime_r(), gmtime_r(), and localtime_r(), should be used with multiple threads. 

AES Support Level:
Full use −− asctime(), ctime(), gmtime(), localtime(), mktime()

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() and ctime() functions return a pointer to a character string that expresses the time in a fixed format. 

Upon successful completion, the gmtime() function returns a pointer to a tm structure, which contains converted GMT time information. 

Upon successful completion, the localtime() functions return a pointer to a tm structure, which contains converted local time. 

Upon successful completion, the mktime() function returns the specified time since the Epoch written as a value of type time_t .  On error, this function returns the value (time_t)−1, and sets errno to indicate the error. 

Upon successful completion, the asctime_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

If any of these functions fails, errno may be set to the following value:

[EINVAL]The buffer, timer, or timeptr parameter is null, the len parameter is less than 1. 

RELATED INFORMATION

Functions: difftime(3) getenv(3), strftime(3), time(3) timezone(3).