View source for C date and time functions

{{Short description|Library of C programs}}
{{manual|date=October 2014}}
{{Use dmy dates|date=December 2020}}
{{C Standard Library}}
The '''C date and time functions''' are a group of functions in the [[C standard library|standard library]] of the [[C (programming language)|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 [[system time|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|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/enwiki/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/enwiki/w/c/chrono/time time]</code>
| returns the current [[system time|time of the system]] as a <code>time_t</code> value, number of seconds, (which is usually time since an [[Epoch (computing)|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/enwiki/w/c/chrono/clock clock]</code>
| returns a [[CPU time|processor tick count]] associated with the process
|- id=timespec_get
| <code>[https://en.cppreference.com/enwiki/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/enwiki/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/enwiki/w/c/chrono/ctime ctime]</code>
| converts a <code>time_t</code> value to a textual representation
|- id=strftime
| <code>[https://en.cppreference.com/enwiki/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/enwiki/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/enwiki/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/enwiki/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/enwiki/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/enwiki/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/enwiki/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/enwiki/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/enwiki/w/c/chrono/clock_t clock_t]</code>
| process running time type
|- id=timespec
| <code>[https://en.cppreference.com/enwiki/w/c/chrono/timespec 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++ in 2020 in std::chrono.

==Example==

The following C source code prints the current time to the [[Standard streams|standard output stream]].
<syntaxhighlight lang="c">
#include <time.h>
#include <stdlib.h>
#include <stdio.h>

int main(void)
{
    time_t current_time;
    char* c_time_string;

    /* Obtain current time. */
    current_time = time(NULL);

    if (current_time == ((time_t)-1))
    {
        (void) fprintf(stderr, "Failure to obtain the current time.\n");
        exit(EXIT_FAILURE);
    }

    /* Convert to local time format. */
    c_time_string = ctime(&current_time);

    if (c_time_string == NULL)
    {
        (void) fprintf(stderr, "Failure to convert the current time.\n");
        exit(EXIT_FAILURE);
    }

    /* Print to stdout. ctime() has already added a terminating newline character. */
    (void) printf("Current time is %s", c_time_string);
    exit(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]]