ctime(3)ctime(3)NAME
asctime, asctime_r, ctime, ctime_r, gmtime, gmtime_r, localtime, local‐
time_r, mktime, ctime64, ctime64_r, gmtime64, gmtime64_r, localtime64,
localtime64_r, mktime64 - converts time units
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 );
[Tru64 UNIX] The following functions are supported in order to main‐
tain 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 Tru64 UNIX extensions and do
not conform to current standards. These functions are provided to sup‐
port 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 );
LIBRARY
Standard C Library (libc.so, libc.a)
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
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 charac‐
ter 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 vari‐
ables, 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 point‐
ers to static data.
The tm structure, which is defined in the <time.h> header file, con‐
tains 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 option:
tm_isdst = 0 for Standard Time
tm_isdst = 1 for Daylight Time
long tm_gmtoff Seconds east of Greenwich. (Negative values indi‐
cate
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 fea‐
ture 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\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 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
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 deter‐
mine 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
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() counter‐
parts, but they 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 multi‐
ple threads.
As with their counterpart functions above, the ctime64(), gmtime64(),
and localtime64() functions are not supported for multithreaded appli‐
cations. Instead, their reentrant equivalents --ctime64_r(),
gmtime64_r(), and localtime64_r()-- should be used with multiple
threads. 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.
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 infor‐
mation.
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.
[Tru64 UNIX] 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 Decem‐
ber 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.
[Tru64 UNIX] 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 they use the
time64_t data type in place of time_t.
ERRORS
With the exception of mktime() and mktime64(), if any of these func‐
tions fails, errno may be set to the following value: [Tru64 UNIX] The
buffer, 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, respectively,
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. [Tru64 UNIX] 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.
SEE ALSO
Functions: difftime(3), getenv(3), strftime(3), time(3), timezone(3)
Standards: standards(5)ctime(3)
