C date and time functions
This articleis written likea manual or guide.(October 2014) |
C standard library(libc) |
---|
General topics |
Miscellaneous headers |
TheC date and time functionsare a group of functions in thestandard libraryof theC programming languageimplementing date and time manipulation operations.[1]They provide support fortimeacquisition, conversion between date formats, and formatted output to strings.
History
[edit]The format string used instrftime
traces back to at leastPWB/UNIX 1.0,released in 1977. Itsdate
system command includes various formatting options.[2][3]In 1989, the ANSI C standard is released includingstrftime
and other date and time functions.[4]
Overview of functions
[edit]The C date and time operations are defined in thetime.h
header file(ctime
header inC++).
Identifier | Description | |
---|---|---|
Time manipulation |
difftime
|
computes the difference in seconds between twotime_t values
|
time
|
returns the currenttime of the systemas atime_t value, number of seconds, (which is usually time since anepoch,typically theUnix epoch). The value of the epoch is operating system dependent; 1900 and 1970 are often used. See RFC 868.
| |
clock
|
returns aprocessor tick countassociated with the process | |
timespec_get (C11)
|
returns a calendar time based on a time base | |
Format conversions |
asctime
|
converts astruct tm object to a textual representation (deprecated)
|
ctime
|
converts atime_t value to a textual representation
| |
strftime
|
converts astruct tm object to custom textual representation
| |
strptime
|
converts a string with time information to astruct tm
| |
wcsftime
|
converts astruct tm object to custom wide string textual representation
| |
gmtime
|
converts atime_t value to calendar time expressed asCoordinated Universal Time[5]
| |
localtime
|
converts atime_t value to calendar time expressed as local time
| |
mktime
|
converts calendar time to atime_t value.
| |
Constants | CLOCKS_PER_SEC
|
number of processor clock ticks per second |
TIME_UTC
|
time base for UTC | |
Types | struct tm
|
broken-downcalendartime type: year, month, day, hour, minute, second |
time_t
|
arithmetic time type (typically time since theUnix epoch) | |
clock_t
|
process running time type | |
timespec
|
time with seconds and nanoseconds |
Thetimespec
and related types were originally proposed by Markus Kuhn to provide a variety of time bases, but onlyTIME_UTC
was accepted.[6]The functionalities were, however, added to C++ in 2020 in std::chrono.
Example
[edit]The following C source code prints the current time to thestandard output stream.
#include<time.h>
#include<stdlib.h>
#include<stdio.h>
intmain(void)
{
time_tcurrent_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
[edit]References
[edit]- ^ISO/IEC 9899:1999 specification(PDF).p. 351, § 7.32.2.
- ^"PWB1 date system command - man page".tuhs.org.
- ^"date.c sourcecode of PWB1".tuhs.org.
- ^"Rationale for American National Standard for Information Systems - Programming Language - C - Date and Time".lysator.liu.se.
- ^open-std.org - Committee Draft -- May 6, 2005page 355
- ^Markus Kuhn."Modernized API for ISO C".cl.cam.ac.uk.