ctime(3) Library Functions Manual ctime(3)
NAME
asctime, asctime_r, ctime, ctime_r, gmtime, gmtime_r, localtime, localtime_r, mktime, ctime64, ctime64_r, gmtime64, gmtime64_r, local-
time64, localtime64_r, mktime64 - 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) ;
[Compaq] 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) ;
The following function declarations are Compaq extensions and do not conform to current standards. These functions are provided to support
the time64_t data type and are accessible only when the _TIME64_T feature macro is defined during compilation.
#include <time.h>
char *ctime64(
const time64_t *timer64) ;
char *ctime64_r(
const time64_t *timer64,
char *buffer) ;
struct tm *gmtime64(
const time64_t *timer64) ;
struct tm *gmtime64_r(
const time64_t *timer64,
struct tm *result) ;
struct tm *localtime64(
const time64_t *timer64 ) ;
struct tm *localtime64_r(
const time64_t *timer64,
struct tm *result) ;
time64_t mktime64(
struct tm *timeptr) ;
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 of type time_t that specifies a time
value in seconds since the Epoch. Points to a variable of type time64_t that specifies a time value in seconds since the Epoch. 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_sec Seconds after the minute [0-60]
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 Days since Sunday [0-6]
int tm_yday Days since January 1 [0-365]
int tm_isdst Daylight Saving Time flag
long tm_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 time64_t variable, also defined in <time.h>, contains the number of seconds since the Epoch, 00:00:00 UTC 1 Jan 1970, but is a 64-bit
signed value capable of storing a wider range of values than those of a 32-bit time_t. This data type is only available when the _TIME64_T
feature macro is defined during compilation. See the time(3) reference page for additional details.
A string used to represent a time value has a five-field format. For example:
Tue Nov 9 15:37:29 1993
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.
The ctime64, gmtime64, localtime64, and mktime64 functions behave as their ctime, gmtime, localtime, and mktime counterparts (respec-
tively), but accept or return values of type time64_t instead of time_t, providing the ability to handle times beyond the range of a 32-bit
time_t. These function declarations are only available when the _TIME64_T feature macro is defined during compilation. See the time(3)
reference page for additional details.
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.
As their counterpart functions above, the ctime64, gmtime64 and localtime64 functions are not supported for multithreaded applications.
Instead their reentrant equivalents, ctime64_r gmtime64_r, and localtime64_r, should be used with multiple threads. These function decla-
rations are only available when the _TIME64_T feature macro is defined during compilation. See the time(3) reference page for additional
details.
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.
[Compaq] 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.
[Compaq] 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.
The ctime64, ctime64_r gmtime64, gmtime64_r, localtime64, localtime64_r, and mktime64 functions have return value behavior consistent with
their counterparts described above, but use the time64_t data type in place of time_t.
ERRORS
With the exception of mktime() and mktime64(), if any of these functions fails, errno may be set to the following value: [Compaq] The buf-
fer, timer, timer64, or timeptr parameter is null, the len parameter is less than 1.
If mktime() or mktime64() are not able to represent the time since the Epoch, they return the value (time_t)-1 or (time64_t)-1, respec-
tively, and set errno to ERANGE as defined below.
If the localtime64() or gmtime64() functions are called with a time64_t value that exceeds their limits, they return a null pointer and set
errno to ERANGE as defined below. These functions are currently limited to 35-bit signed values, providing an effective range of Thu Aug 4
22:06:56 1425 GMT to Wed May 30 01:53:03 2514 GMT. [Compaq] The time since the Epoch cannot be represented by mktime or mktime64, or the
value passed to the localtime64() or gmtime64() functions is out of range.
RELATED INFORMATION
Functions: difftime(3), getenv(3), strftime(3), time(3), timezone(3)
Standards: standards(5) delim off
ctime(3)