 |
Index for
Section 3 |
|
 |
Alphabetical
listing for C |
|
 |
Bottom of
page |
|
ctime(3)
NAME
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
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 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 );
LIBRARY
Standard C Library (libc.so, libc.a)
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
timeptr
Points to a type tm structure that defines space for a broken-down time
value.
timer
Points to a variable of type time_t that specifies a time value in
seconds since the Epoch.
timer64
Points to a variable of type time64_t that specifies a time value in
seconds since the Epoch.
buffer
Points to a character array that is at least 26 bytes long. This array
is used to store the generated date and time string.
len 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 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 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, 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 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.
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.
[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.
ERRORS
With the exception of mktime() and mktime64(), if any of these functions
fails, errno may be set to the following value:
[EINVAL]
[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.
[ERANGE]
[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)
|
Index for
Section 3 |
|
|
Alphabetical
listing for C |
|
 |
Top of
page |
|