ctime() — Convert Time to Character String

Format

#include <time.h>
char *ctime(const time_t *time);

Language Level

ANSI

Threadsafe

Use ctime_r() instead.

Locale Sensitive

The behavior of this function might be affected by the LC_TOD category of the current locale. For more information, see Understanding CCSIDs and Locales.

Description

The ctime() function converts the time value pointed to by time to local time in the form of a character string. A time value is usually obtained by a call to the time() function.

The string result that is produced 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

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 preceded with a zero. The new-line character (\n) and the null character (\0) occupy the last two positions of the string.

Return Value

The ctime() function returns a pointer to the character string result. If the function is unsuccessful, it returns NULL. A call to the ctime() function is equivalent to:

   asctime(localtime(&anytime))

Note: The asctime() and ctime() functions, and other time functions can use a common, statically allocated buffer to hold the return string. Each call to one of these functions might destroy the result of the previous call. The asctime_r(), ctime_r(), gmtime_r(), and localtime_r() functions do not use a common, statically allocated buffer to hold the return string. These functions can be used in place of asctime(), ctime(), gmtime(), and localtime() if reentrancy is desired.

Example

This example polls the system clock using time(). 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));
}