C date and time functions
Library of C programs
From Wikipedia, the free encyclopedia
The C date and time functions are a group of functions in the standard library of the C programming language implementing date and time manipulation operations.[1] They provide support for time acquisition, conversion between date formats, and formatted output to strings.
History
The format string used in strftime traces back to at least PWB/UNIX 1.0, released in 1977. Its date system command includes various formatting options.[2][3] In 1989, the ANSI C standard is released including strftime and other date and time functions.[4]
Overview of functions
The C date and time operations are defined in the <time.h> header file (<ctime> header in C++).
| Identifier | Description | |
|---|---|---|
| Time manipulation |
difftime |
computes the difference in seconds between two time_t values |
time |
returns the current time of the system as a time_t value, number of seconds, (which is usually time since an epoch, typically the Unix epoch). The value of the epoch is operating system dependent; 1900 and 1970 are often used. See RFC 868. | |
clock |
returns a processor tick count associated with the process | |
timespec_get (C11) |
returns a calendar time based on a time base | |
| Format conversions |
asctime |
converts a struct tm object to a textual representation (deprecated) |
ctime |
converts a time_t value to a textual representation | |
strftime |
converts a struct tm object to custom textual representation | |
strptime |
converts a string with time information to a struct tm | |
wcsftime |
converts a struct tm object to custom wide string textual representation | |
gmtime |
converts a time_t value to calendar time expressed as Coordinated Universal Time[5] | |
localtime |
converts a time_t value to calendar time expressed as local time | |
mktime |
converts calendar time to a time_t value. | |
| Constants | CLOCKS_PER_SEC |
number of processor clock ticks per second |
TIME_UTC |
time base for UTC | |
| Types | struct tm |
broken-down calendar time type: year, month, day, hour, minute, second |
time_t |
arithmetic time type (typically time since the Unix epoch) | |
clock_t |
process running time type | |
struct timespec |
time with seconds and nanoseconds |
The timespec and related types were originally proposed by Markus Kuhn to provide a variety of time bases, but only TIME_UTC was accepted.[6] The functionalities were, however, added to C++ with the release of C++20 in std::chrono.
Example
The following C source code prints the current time to the standard output stream.
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
int main(void) {
// Obtain current time.
time_t current_time = time(NULL);
if (current_time == (time_t)-1) {
fprintf(stderr, "Failure to obtain the current time.\n");
return EXIT_FAILURE;
}
// Convert to local time format.
char* time_string = ctime(¤t_time);
if (!time_string) {
fprintf(stderr, "Failure to convert the current time.\n");
return EXIT_FAILURE;
}
// Print to stdout. ctime() has already added a terminating newline character.
printf("Current time is %s", time_string);
return EXIT_SUCCESS;
}
The output is:
Current time is Thu Sep 15 21:18:23 2016
