OSF

NAME

asctime, asctime_r, ctime, ctime_r, difftime, gmtime, gmtime_r, localtime, localtime_r, mktime, timezone, tzset − Converts time units

LIBRARY

Standard C Library (libc.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 );

double difftime(
    time_t time1,
    time_t time2) ;

struct tm ∗gmtime(
    const time_t ∗timer) ;

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

struct tm ∗localtime(
    const time_t ∗timer ) ;

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

time_t mktime(
    struct tm ∗timeptr) ;

void tzset(void) ;
    extern char ∗tzname[] ;
    extern long timezone ;
    extern int daylight ;

PARAMETERS

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

time1Specifies a time value expressed in seconds. 

time2Specifies a time value expressed in seconds. 

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(), asctime_r(), ctime(), difftime(), gmtime(), gmtime_r(), localtime(), localtime_r(), mktime(), and tzset() functions are used to convert time units to strings, to store converted time units for subsequent processing, and to convert stored time information to other time units. Time information used in these functions is stored in a type tm structure, which is defined in the time.h include file. 

The asctime() function converts type tm structure broken-down time information pointed to by the timeptr parameter to a date and time string with the following 5-field format:

Sun Sep 16 01:03:52 1973

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

The ctime() function converts the time in seconds since the Epoch, pointed to by the timer parameter, to a character string.  The Epoch is taken as 00:00:00 GMT 1 Jan 1970. The character string specifies local time in the same format as does the asctime() function. Local time-zone information is set as though the tzset() function were called.  This function is equivalent to asctime (localtime (timer)). 

The reentrant version of this function is identical, except that it stores the string in the buffer parameter up to len characters. 

The difftime() function returns a signed tmme value in seconds that is the difference between the values of the time1 and time2 parameters, also expressed in seconds. 

The gmtime() function converts the time in seconds since the Epoch, pointed to by the timer parameter, into broken-down time, expressed as CUT (Coordinated Universal Time). Broken-down time is stored in the type tm structure pointed to by the return value of the gmtime() function. 

The gmtime_r() function is the reentrant version of gmtime().  This information is stored in the tm structure passed in the result parameter. 

The localtime() function converts the time in seconds since the Epoch, pointed to by the timer parameter, into broken-down time, expressed as local time. This function corrects for the time-zone and any seasonal time adjustments. Broken-down time is stored in the type tm structure pointed to by the return value of this function.  Local time-zone information is set as though the tzset() function were called. 

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

The mktime() function converts the broken-down time, expressed as local time, in the type tm structure pointed to by the timeptr parameter, into a time since the Epoch in the same format as that of values returned by the time() function.  The original values of parameters timeptr->tm_wday and timeptr->tm_yday of the structure are ignored, and the original values of other members of the structure are not restricted to the ranges defined in the time.h header file. The range [0, 61] for structure member tm_sec allows for an occasional leap second or double leap second. 

A positive or 0 (zero) value for member tm_isdst tells the mktime() function whether daylight saving time is in effect.  A negative value for tm_isdst tells the mktime() function to find out whether daylight saving time is in effect for the specified time.  Local time-zone information is set as though the tzset() function were called. 

On successful completion, values for the timeptr->tm_wday and timeptr->tm_yday members of the structure are set, and the other members are set to specified times since the Epoch, but with their values forced to the ranges indicated above; the final value of timeptr->tm_mday is not set until the values of members timeptr->tm_mon and timeptr->tm_year are determined. 

The tzset() function uses the value of the environment variable TZ to set time conversion information used by the localtime(), localtime_r(), ctime(), ctime_r(), strftime(), and mktime() functions.  When environment variable TZ is absent, implementation-defined default time-zone information is used. 

When the TZ environment variable is defined, the defined value overrides the default time-zone value. The environment facility contains formatted time zone information specified by TZ. Environment variable  TZ is usually set when a system is started with the value that is defined in either the /etc/environment or /etc/profile files.  However, TZ may also be set by a user as a regular environment variable for converting to alternate time zones. 

The tzset() function sets the external variable tzname as follows:

tzname[0] = std ;

tzname[1] = dst ;

where std and dst are the strings designating standard and daylight saving time zones, respectively, as described for the TZ environment variable. 

The tzset() function also sets the external variable daylight to 0 (zero) when daylight saving time conversions should never be applied for the time zone in use; otherwise daylight is set to a nonzero value.  The external variable timezone is set to the difference, in seconds, between Coordinated Universal Time (CUT) and local standard time. In the following table, entries in the TZ column are time-zone environmental variables, and entries in the Timezone column are time units expressed as UTC time. 

External variable tzname specifies the name of the standard time zone (tzname[0]) and of the time zone when daylight saving time is in effect (tzname[1]). For example:

extern char ∗tzname[2] = {"EST","EDT"};

External variable timezone specifies the difference, in seconds, between GMT and local standard time. For example, the value of timezone is 5 ∗ 60 ∗ 60 for U.S. Eastern Standard Time. 

External variable daylight is set nonzero when a daylight saving time conversion should be applied. By default, this conversion follows standard U.S. time conventions; other time conventions may be specified.  The default conversion algorithm adjusts for peculiarities of U.S. daylight saving time in 1974 and 1975. 

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. 

The difftime(), mktime(), and tzset() functions are supported for multi-threaded applications. 

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

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 difftime() function returns a value, expressed in seconds, that is the difference between the values of parameters time1 and time2. 

Upon successful completion, the gmtime() and gmtime_r() functions return a pointer to a type tm broken-down time structure, which contains converted GMT time information. When UTC is not available, this function returns a null pointer. 

Upon successful completion, the localtime() functions return a pointer to a type tm  broken-down time 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, or whenever the time since the Epoch cannot be represented, this function returns the value (time_t)−1, and sets errno to indicate the error.  This function does not return a value. 

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 or timer parameter is null, the len parameter is 0 (zero), or the specified broken-down time can not be represented as time since the Epoch. 

RELATED INFORMATION

Functions: getenv(3), strftime(3), time(3)