ctime64, localtime64, gmtime64, mktime64, difftime64, or asctime64 Subroutine

Purpose

Converts the formats of date and time representations.

Library

Standard C Library (libc.a)

Syntax

#include <time.h>


char *ctime64 (Clock)
const time64_t *Clock;

struct tm *localtime64 (Clock)
const time64_t *Clock;

struct tm *gmtime64 (Clock)
const time64_t *Clock;


time64_t mktime64(Timeptr)
struct tm *Timeptr;

double difftime64(Time1, Time0)
time64_t Time0, Time1;

char *asctime64 (Tm)
const struct tm *Tm;

Description

Attention: Do not use the ctime, localtime, gmtime, or asctime subroutine in a multithreaded environment. See ctime64_r, localtime64_r, gmtime64_r, or asctime64_r Subroutine for multithread alternatives.

The ctime64 subroutine converts a time value pointed to by the Clock parameter, which represents the time in seconds since 00:00:00 Coordinated Universal Time (UTC), January 1, 1970, into a 26-character string in the following form:

Sun Sept 16 01:03:52 1973\n\0

The width of each field is always the same as shown here.

The ctime64 subroutine adjusts for the time zone and daylight saving time, if it is in effect.

The localtime64 subroutine converts the 64 bit long pointed to by the Clock parameter, which contains the time in seconds since 00:00:00 UTC, 1 January 1970, into a tm structure. The localtime64 subroutine adjusts for the time zone and for daylight saving time, if it is in effect. Use the time-zone information as though localtime64 called tzset.

The gmtime64 subroutine converts the 64 bit long pointed to by the Clock parameter into a tm structure containing the Coordinated Universal Time (UTC), which is the time standard that the operating system uses.

Note: UTC is the international time standard intended to replace GMT.

The mktime64 subroutine is the reverse function of the localtime64 subroutine. The mktime64 subroutine converts the tm structure into the time in seconds since 00:00:00 UTC, 1 January 1970. The tm_wday and tm_yday fields are ignored, and the other components of the tm structure are not restricted to the ranges specified in the /usr/include/time.h file. The value of the tm_isdst field determines the following actions of the mktime64 subroutine:

Item	Description
0	Initially presumes that Daylight Savings Time (DST) is not in effect.
>0	Initially presumes that DST is in effect.
-1	Actively determines whether DST is in effect from the specified time and the local time zone. Local time zone information is set by the tzset subroutine.

Upon successful completion, the mktime64 subroutine sets the values of the tm_wday and tm_yday fields appropriately. Other fields are set to represent the specified time since January 1, 1970. However, the values are forced to the ranges specified in the /usr/include/time.h file. The final value of the tm_mday field is not set until the values of the tm_mon and tm_year fields are determined.

Note: The mktime64 subroutine cannot convert time values before 00:00:00 UTC, January 1, 1970 and after 23:59:59 UTC, December 31, 9999.

Note: The difftime64 subroutine computes the difference between two calendar times: the Time1 and Time0 parameters.

Note: The asctime64 subroutine converts a tm structure to a 26-character string of the same format as ctime64.

Parameters

Item	Description
Clock	Specifies the pointer to the time value in seconds.
Timeptr	Specifies the pointer to a tm structure.
Time1	Specifies the pointer to a time64_t structure.
Time0	Specifies the pointer to a time64_t structure.
Tm	Specifies the pointer to a tm structure.

Return Values

Attention: The return values point to static data that is overwritten by each call.

The mktime64 subroutine returns the specified time in seconds encoded as a value of type time64_t. If the time cannot be represented, the function returns the value (time64_t)-1.

The localtime64 and gmtime64 subroutines return a pointer to the tm struct .

The ctime64 and asctime64 subroutines return a pointer to a 26-character string.

The difftime64 subroutine returns the difference expressed in seconds as a value of type long double.