C date and time functions
Library of C programs
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. They provide support for time acquisition, conversion between date formats, and formatted output to strings.
01History
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. In 1989, the ANSI C standard is released including strftime and other date and time functions.
02Overview 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 | |
| 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. The functionalities were, however, added to C++ with the release of C++20 in std::chrono.
03Example
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 2016Sources and credits
This article is adapted from the Wikipedia article “C date and time functions”, written by its contributors and licensed under CC BY-SA 4.0. Fathomly has changed the layout, removed citation markers, navigation and maintenance notices, and adjusted punctuation. This adapted version is shared under the same license. For references, see the original article.
Fathomly is not affiliated with or endorsed by the Wikimedia Foundation. Spotted a problem? Tell us.
