ctime(), ctime64() — Convert time to character string

Standards

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2 C99 Single UNIX Specification, Version 3 Language Environment®	both

Format

#include <time.h>

char *ctime(const time_t *timer);

#define _LARGE_TIME_API
#include <time.h>

char  *ctime64 (const time64_t *timer);

General description

Converts the calendar time pointed to by timer to local time in the form of a character string. A value for timer is usually obtained by a call to the time() function.

The ctime() function is equivalent to the function call: asctime(localtime(timer))

The function ctime64() will behave exactly like ctime() except it will convert a time64_t value pointing to a calendar time beyond 03:14:07 UTC on January 19, 2038 with a limit of 23:59:59 UTC on December 31, 9999.

Returned value

If successful, ctime() returns a pointer to a date and time string. The string returned by ctime() contains exactly 26 characters and has the format:

   "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n"

For example: Mon Jul 16 02:03:55 1987\n\0

If an error occurs, ctime() returns no value.

Notes:

This function is sensitive to time zone information which is provided by:
- The TZ environmental variable when POSIX(ON) and TZ is correctly defined, or by the _TZ environmental variable when POSIX(OFF) and _TZ is correctly defined.
- The LC_TOD category of the current locale if POSIX(OFF) or TZ is not defined.
The time zone external variables tzname, timezone, and daylight declarations remain feature test protected in time.h.
The calendar time returned by a call to the time() function begins at epoch, which was at 00:00:00 Coordinated Universal Time (UTC), January 1, 1970.
The ctime() function uses a 24-hour clock format.
The days are abbreviated to: Sun, Mon, Tue, Wed, Thu, Fri, and Sat.
The months are abbreviated to: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, and Dec.
All fields have a constant width.
Dates with only one digit are padded with a blank space. Single digit time values are padded with a zero.
The newline character (\n) and the NULL character (\0) occupy the last two positions of the string.
The asctime(), ctime(), and other time functions may use a common, statically allocated buffer for holding the return string. Each call to one of these functions may destroy the result of the previous call.

When neither TZ nor _TZ is defined, the current locale is interrogated for time zone information. If neither TZ nor _TZ is defined and LC_TOD time zone information is not present in the current locale, a default value is applied to local time. POSIX programs simply default to Coordinated Universal Time (UTC), while non-POSIX programs establish an offset from UTC based on the setting of the system clock.

For more information about customizing a time zone to work with local time, see “Customizing a time zone” in z/OS XL C/C++ Programming Guide.

Error Code: Description
EOVERFLOW: The result cannot be represented.

Example

CELEBC33

⁄* CELEBC33                                      

   This example polls the system clock by using the library                     
   function &ttime..                                                            
   It then prints a message giving the current date and time.                   
                                                                                
 *⁄                                                                             
#include <time.h>                                                               
#include <stdio.h>                                                              
                                                                                
int main(void)                                                                  
{                                                                               
   time_t ltime;                                                                
                                                                                
   time(&ltime);                                                                
   printf("the time is %s", ctime(&ltime));                                     
}

Output

the time is Fri Jun 16 16:03:38 2001