ctime_r, localtime_r, gmtime_r, or asctime_r Subroutine

Purpose

Converts the formats of date and time representations.

Library

Thread-Safe C Library (libc_r.a)

Syntax

#include <time.h>

char *ctime_r(Timer, BufferPointer)
const time_t * Timer;
char * BufferPointer;

struct tm *localtime_r(Timer, CurrentTime)
const time_t * Timer;
struct tm * CurrentTime;

struct tm *gmtime_r(Timer, XTime)
const time_t * Timer;
struct tm * XTime;

char *asctime_r(TimePointer, BufferPointer)
const struct tm * TimePointer;
char * BufferPointer;

Description

The ctime_r subroutine converts a time value pointed to by the Timer parameter, which represents the time in seconds since 00:00:00 Coordinated Universal Time (UTC), January 1, 1970, into the character array pointed to by the BufferPointer parameter. The character array should have a length of at least 26 characters so the converted time value fits without truncation. The converted time value string takes the form of the following example:

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

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

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

The localtime_r subroutine converts the time_t structure pointed to by the Timer parameter, which contains the time in seconds since 00:00:00 UTC, January 1, 1970, into the tm structure pointed to by the CurrentTime parameter. The localtime_r subroutine adjusts for the time zone and for daylight saving time, if it is in effect.

The gmtime_r subroutine converts the time_t structure pointed to by the Timer parameter into the tm structure pointed to by the XTime parameter.

The tm structure is defined in the time.h header file. The time.h file contains declarations of these subroutines, externals, and the tm structure.

The asctime_r subroutine converts the tm structure pointed to by the TimePointer parameter into a 26-character string in the same format as the ctime_r subroutine. The results are placed into the character array, BufferPointer. The BufferPointer parameter points to the resulting character array, which takes the form of the following example:

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

Programs using this subroutine must link to the libpthreads.a library.

Parameters

Item Description
Timer Points to a time_t structure, which contains the number of seconds since 00:00:00 UTC, January 1, 1970.
BufferPointer Points to a character array at least 26 characters long.
CurrentTime Points to a tm structure. The result of the localtime_r subroutine is placed here.
XTime Points to a tm structure used for the results of the gmtime_r subroutine.
TimePointer Points to a tm structure used as input to the asctime_r subroutine.

Return Values

The localtime_r and gmtime_r subroutines return a pointer to the tm structure. The asctime_r returns NULL if either TimePointer or BufferPointer are NULL.

The ctime_r and asctime_r subroutines return a pointer to a 26-character string. The ctime_r subroutine returns NULL if the BufferPointer is NULL.

Files

Item Description
/usr/include/time.h Defines time macros, data types, and structures.