asctime, asctime_r, ctime, ctime_r, gmtime, gmtime_r,
localtime, localtime_r, mktime, ctime64, ctime64_r,
gmtime64, gmtime64_r, localtime64, localtime64_r, mktime64
- converts time units
#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 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 Tru64 UNIX 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 );
Standard C Library (libc.so, libc.a)
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.
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.
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 option:
tm_isdst = 0 for Standard Time
tm_isdst = 1 for Daylight Time
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\n\0
The asctime() function converts the tm structure pointed
to by the timeptr parameter to a string with this fivefield
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, 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.
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 with 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 declarations are only available when the
_TIME64_T feature macro is defined during compilation. See
the time(3) reference page for additional details.
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.
[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
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.
[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.
With the exception of mktime() and mktime64(), if any of
these functions 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.
Functions: difftime(3), getenv(3), strftime(3), time(3),
timezone(3)
Standards: standards(5)
ctime(3)
[ Back ] |
