Content-type: text/html Man page of ctime

ctime

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

asctime, asctime_r, ctime, ctime_r, gmtime, gmtime_r, localtime, localtime_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 standards 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 industry 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 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.

[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, contains the following elements:
int tm_secSeconds after the minute [0-60]
int tm_minMinutes after the hour [0-59]
int tm_hourHours since midnight [0-23]
int tm_mdayDay of the month [1-31]
int tm_monMonths since January [0-11]
int tm_yearYears since 1900
int tm_wdayDays since Sunday [0-6]
int tm_ydayDays since January 1 [0-365]
int tm_isdstDaylight Saving Time flag
long tm_gmtoffSeconds east of Greenwich. (Negative values indicate
seconds west of Greenwich.)
char tm_zoneTimezone 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 function 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 information 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 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 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 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 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 multithreaded applications.

[POSIX] Instead, their reentrant equivalents, asctime_r, ctime_r, gmtime_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 return 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 indicate 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 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

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 returns the value (time_t)-1 and sets errno to the following value: [Digital]  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


 

Index

NAME
LIBRARY
SYNOPSIS
STANDARDS
PARAMETERS
DESCRIPTION
NOTES
RETURN VALUES
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:42:14 GMT, October 02, 2010