ctime(), ctime_r()

Updated: April 19, 2023

Convert calendar time to local time

Synopsis:

#include <time.h>

char* ctime( const time_t* timer );

char* ctime_r( const time_t* timer, 
               char* buf );

Arguments:

timer
A pointer to a time_t object that contains the time that you want to convert to a string.
buf
(ctime_r() only) A buffer in which ctime_r() can store the resulting string. This buffer must be large enough to hold at least 26 characters.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The ctime() and ctime_r() functions convert the time pointed to by timer to local time and formats it as a string containing exactly 26 characters in the form:

Tue May  7 10:40:27 2002\n\0
This function: Is equivalent to calling:
ctime() asctime( localtime ( timer ) );
ctime_r() asctime_r( localtime ( timer ), buf )
Note: The ctime() function places the result string in a static buffer that's reused each time you call ctime() or asctime(). Calling gmtime() or localtime() could also change the date in this static buffer.

The result string for ctime_r() is contained in the buffer pointed to by buf.

All fields have a constant width. The newline character '\n' and NUL character '\0' occupy the last two positions of the string.

Whenever the ctime() or ctime_r() functions are called, the tzset() function is also called.

The calendar time is usually obtained by using the time() function. That time is Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time (GMT)).

You typically set the time on the computer with the date command to reflect Coordinated Universal Time (UTC), and then use the TZ environment variable or _CS_TIMEZONE configuration string to establish the local time zone. For more information, see Setting the time zone in the Configuring Your Environment chapter of the QNX Neutrino User's Guide.

Returns:

A pointer to the string containing the formatted local time, or NULL if an error occurs.

Classification:

ctime() is ANSI, POSIX 1003.1 OB; ctime_r() is POSIX 1003.1 OB. These functions are marked as obsolescent, and may be removed from a future version of the standard.

Table 1. ctime()
Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread No
Table 2. ctime_r()
Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes

Caveats:

The asctime() and ctime() functions place their results in a static buffer that's reused for each call to asctime() or ctime().