Login
Login

C date and time functions#time

{{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.{{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}} 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.{{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}}{{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}} In 1989, the ANSI C standard is released including strftime and other date and time functions.{{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}}

Overview of functions

The C date and time operations are defined in the time.h header file (ctime header in C++).

class="wikitable" style="font-size:0.85em"

!

! Identifier

! Description

id=difftime

! rowspan=4 | Time
manipulation

| [https://en.cppreference.com/w/c/chrono/difftime difftime]

| computes the difference in seconds between two time_t values

id=time

| [https://en.cppreference.com/w/c/chrono/time 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.

id=clock

| [https://en.cppreference.com/w/c/chrono/clock clock]

| returns a processor tick count associated with the process

id=timespec_get

| [https://en.cppreference.com/w/c/chrono/timespec_get timespec_get] (C11)

| returns a calendar time based on a time base

id=asctime

! rowspan=8 | Format
conversions

| [https://en.cppreference.com/w/c/chrono/asctime asctime]

| converts a struct tm object to a textual representation (deprecated)

id=ctime

| [https://en.cppreference.com/w/c/chrono/ctime ctime]

| converts a time_t value to a textual representation

id=strftime

| [https://en.cppreference.com/w/c/chrono/strftime strftime]

| converts a struct tm object to custom textual representation

id=strptime

| [https://linux.die.net/man/3/strptime strptime]

| converts a string with time information to a struct tm

id=wcsftime

| [https://en.cppreference.com/w/c/chrono/wcsftime wcsftime]

| converts a struct tm object to custom wide string textual representation

id=gmtime

| [https://en.cppreference.com/w/c/chrono/gmtime gmtime]

| converts a time_t value to calendar time expressed as Coordinated Universal Time[http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1124.pdf open-std.org - Committee Draft -- May 6, 2005] page 355

id=localtime

| [https://en.cppreference.com/w/c/chrono/localtime localtime]

| converts a time_t value to calendar time expressed as local time

id=mktime

| [https://en.cppreference.com/w/c/chrono/mktime mktime]

| converts calendar time to a time_t value.

id=CLOCKS_PER_SEC

! rowspan=2 | Constants

| [https://en.cppreference.com/w/c/chrono/CLOCKS_PER_SEC CLOCKS_PER_SEC]

| number of processor clock ticks per second

TIME_UTC

| time base for UTC

id=tm

! rowspan=4 | Types

| [https://en.cppreference.com/w/c/chrono/tm struct tm]

| broken-down calendar time type: year, month, day, hour, minute, second

id=time_t

| [https://en.cppreference.com/w/c/chrono/time_t time_t]

| arithmetic time type (typically time since the Unix epoch)

id=clock_t

| [https://en.cppreference.com/w/c/chrono/clock_t clock_t]

| process running time type

id=timespec

| [https://en.cppreference.com/w/c/chrono/timespec struct timespec]

| 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.{{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}} 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 output stream.

  1. include
  2. include
  3. include

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(¤t_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);

}

The output is:

Current time is Thu Sep 15 21:18:23 2016

See also

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