ctime(), ctime64() — Convert time to character string
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
ISO C |
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
"%.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.
- 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 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
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(<ime);
printf("the time is %s", ctime(<ime));
}
the time is Fri Jun 16 16:03:38 2006
Related information
- locale.h
- time.h
- asctime(), asctime64() — Convert time to character string
- asctime_r(), asctime64_r() — Convert date and time to a character string
- ctime_r(), ctime64_r() — Convert time value to date and time character string
- gmtime(), gmtime64() — Convert time to broken-down UTC time
- gmtime_r(), gmtime64_r() — Convert a time value to broken-down UTC time
- localdtconv() — Date and time formatting convention inquiry
- localtime(), localtime64() — Convert time and correct for local time
- localtime_r(), localtime64_r() — Convert time value to broken-down local time
- mktime(), mktime64() — Convert local time
- strftime() — Convert to formatted time
- time(),time64() — Determine current UTC time
- tzset() — Set the time zone