{{Short description|Library of C programs}} {{Use dmy dates|date=December 2020}} {{C Standard Library}} 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.<ref>{{cite book | url=http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf | title=ISO/IEC 9899:1999 specification | at=p. 351, § 7.32.2}}</ref> They provide support for time acquisition, conversion between date formats, and formatted output to strings.
==History==
The format string used in <code>strftime</code> traces back to at least PWB/UNIX 1.0, released in 1977. Its <code>date</code> system command includes various formatting options.<ref>{{cite web |title=PWB1 date system command - man page |url=https://www.tuhs.org/cgi-bin/utree.pl?file=PWB1/usr/man/man1/date.1 |website=www.tuhs.org}}</ref><ref>{{cite web |title=date.c sourcecode of PWB1 |url=https://www.tuhs.org/cgi-bin/utree.pl?file=PWB1/sys/source/s1/date.c |website=www.tuhs.org}}</ref> In 1989, the ANSI C standard is released including <code>strftime</code> and other date and time functions.<ref>{{cite web |title=Rationale for American National Standard for Information Systems - Programming Language - C - Date and Time |url=https://www.lysator.liu.se/c/rat/d12.html#4-12-3-5 |website=www.lysator.liu.se}}</ref>
==Overview of functions==
The C date and time operations are defined in the <code><time.h></code> header file (<code><ctime></code> header in C++).
{| class="wikitable" style="font-size:0.85em" ! ! Identifier ! Description |- id=difftime ! rowspan=4 | Time<br>manipulation | <code>[https://en.cppreference.com/w/c/chrono/difftime difftime]</code> | computes the difference in seconds between two <code>time_t</code> values |- id=time | <code>[https://en.cppreference.com/w/c/chrono/time time]</code> | returns the current time of the system as a <code>time_t</code> 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. |- id=clock | <code>[https://en.cppreference.com/w/c/chrono/clock clock]</code> | returns a processor tick count associated with the process |- id=timespec_get | <code>[https://en.cppreference.com/w/c/chrono/timespec_get timespec_get]</code> (C11) | returns a calendar time based on a time base |- id=asctime ! rowspan=8 | Format<br>conversions | <code>[https://en.cppreference.com/w/c/chrono/asctime asctime]</code> | converts a <code>struct tm</code> object to a textual representation (deprecated) |- id=ctime | <code>[https://en.cppreference.com/w/c/chrono/ctime ctime]</code> | converts a <code>time_t</code> value to a textual representation |- id=strftime | <code>[https://en.cppreference.com/w/c/chrono/strftime strftime]</code> | converts a <code>struct tm</code> object to custom textual representation |- id=strptime | <code>[https://linux.die.net/man/3/strptime strptime]</code> | converts a string with time information to a <code>struct tm</code> |- id=wcsftime | <code>[https://en.cppreference.com/w/c/chrono/wcsftime wcsftime]</code> | converts a <code>struct tm</code> object to custom wide string textual representation |- id=gmtime | <code>[https://en.cppreference.com/w/c/chrono/gmtime gmtime]</code> | converts a <code>time_t</code> value to calendar time expressed as Coordinated Universal Time<ref>[http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf open-std.org - Committee Draft -- May 6, 2005] page 355</ref> |- id=localtime | <code>[https://en.cppreference.com/w/c/chrono/localtime localtime]</code> | converts a <code>time_t</code> value to calendar time expressed as local time |- id=mktime | <code>[https://en.cppreference.com/w/c/chrono/mktime mktime]</code> | converts calendar time to a <code>time_t</code> value. |- id=CLOCKS_PER_SEC ! rowspan=2 | Constants | <code>[https://en.cppreference.com/w/c/chrono/CLOCKS_PER_SEC CLOCKS_PER_SEC]</code> | number of processor clock ticks per second |- | <code>TIME_UTC</code> | time base for UTC |- id=tm ! rowspan=4 | Types | <code>[https://en.cppreference.com/w/c/chrono/tm struct tm]</code> | broken-down calendar time type: year, month, day, hour, minute, second |- id=time_t | <code>[https://en.cppreference.com/w/c/chrono/time_t time_t]</code> | arithmetic time type (typically time since the Unix epoch) |- id=clock_t | <code>[https://en.cppreference.com/w/c/chrono/clock_t clock_t]</code> | process running time type |- id=timespec | <code>[https://en.cppreference.com/w/c/chrono/timespec struct timespec]</code> | time with seconds and nanoseconds |}
The {{code|timespec}} and related types were originally proposed by Markus Kuhn to provide a variety of time bases, but only {{code|TIME_UTC}} was accepted.<ref>{{cite web |author=Markus Kuhn |title=Modernized API for ISO C |url=https://www.cl.cam.ac.uk/~mgk25/time/c/ |website=cl.cam.ac.uk}}</ref> The functionalities were, however, added to C++ with the release of C++20 in <code>std::chrono</code>.
==Example==
The following C source code prints the current time to the standard output stream. <syntaxhighlight lang="c"> #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; }
</syntaxhighlight>
The output is: <syntaxhighlight lang="output"> Current time is Thu Sep 15 21:18:23 2016 </syntaxhighlight>
==See also== * Unix time * Year 2038 problem
==References== {{reflist}}
==External links== {{wikibooks|C Programming|C date and time operations|C Programming/C Reference}} {{clear}}
{{CProLang|state=expanded}}
Category:C standard library Category:Time