C date and time functions

From KYNNpedia
Revision as of 01:17, 26 October 2022 by imported>Dylnuge (as per above, time_t is usually keyed to the Unix epoch; "the epoch" also probably already meant this (as the Unix epoch is common, but one of several epochs that can be selected))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

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>ISO/IEC 9899:1999 specification (PDF). p. 351, § 7.32.2.</ref> They provide support for time acquisition, conversion between date formats, and formatted output to strings.

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<ref>open-std.org - Committee Draft -- May 6, 2005 page 355</ref>
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
timespec time with seconds and nanoseconds

The <syntaxhighlight lang="text" class="" id="" style="" inline="1">timespec</syntaxhighlight> and related types were originally proposed by Markus Kuhn to provide a variety of time bases, but only <syntaxhighlight lang="text" class="" id="" style="" inline="1">TIME_UTC</syntaxhighlight> was accepted.<ref>Markus Kuhn. "Modernized API for ISO C". 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 output stream. <syntaxhighlight lang="c">

  1. include <time.h>
  2. include <stdlib.h>
  3. 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

References

<references group="" responsive="1"></references>

External links