C date and time functions

TheC date and time functionsare a group of functions in thestandard libraryof theC programming languageimplementing date and time manipulation operations.They provide support fortimeacquisition, conversion between date formats, and formatted output to strings.

History

The format string used instrftimetraces back to at leastPWB/UNIX 1.0,released in 1977. Itsdatesystem command includes various formatting options.In 1989, the ANSI C standard is released includingstrftimeand other date and time functions.

Overview of functions

The C date and time operations are defined in thetime.hheader file(ctimeheader inC++).

	Identifier	Description
Time manipulation	difftime	computes the difference in seconds between twotime_tvalues
	time	returns the currenttime of the systemas atime_tvalue, 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 tmobject to a textual representation (deprecated)
	ctime	converts atime_tvalue to a textual representation
	strftime	converts astruct tmobject to custom textual representation
	strptime	converts a string with time information to astruct tm
	wcsftime	converts astruct tmobject to custom wide string textual representation
	gmtime	converts atime_tvalue to calendar time expressed asCoordinated Universal Time
	localtime	converts atime_tvalue to calendar time expressed as local time
	mktime	converts calendar time to atime_tvalue.
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

Thetimespecand related types were originally proposed by Markus Kuhn to provide a variety of time bases, but onlyTIME_UTCwas accepted.The functionalities were, however, added to C++ in 2020 in std::chrono.

Example

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(&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);
}

The output is:

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

See also

• Unix time
• Year 2038 problem