Calendar time

Names specified here
Name	Description		Source	Availability
`difftime()`	Compare times	(·)	`<time.h>`	C89	C90	C95	C99	C11
`gmtime()`	Convert calendar time to UTC	(·)	`<time.h>`	C89	C90	C95	C99	C11
`gmtime_s()`	Convert calendar time to UTC	(·)	`<time.h>`					C11
`localtime()`	Convert calendar time to local time	(·)	`<time.h>`	C89	C90	C95	C99	C11
`localtime_s()`	Convert calendar time to local time	(·)	`<time.h>`					C11
`mktime()`	Create calendar time	(·)	`<time.h>`	C89	C90	C95	C99	C11
`struct tm`	Time type	T	Headers	C89	C90	C95	C99	C11
`time()`	Get calendar time	(·)	`<time.h>`	C89	C90	C95	C99	C11
`time_t`	Calendar-time type	T	`<time.h>`	C89	C90	C95	C99	C11

<time.h> defines a type time_t to represent real or calendar time, independent of any timezone. It is a real type, but nothing can be inferred directly from its arithmetic value. Only the functions difftime, gmtime, gmtime_s, localtime and localtime_s can interpret it in a correct and portable way, and only time and mktime can portably create meaningful values.

#include <time.h>
time_t time(time_t *p);

The function time gets the current real time, returning the value, and assigning it to *p if p is not null.

#include <time.h>
double difftime(time_t t1, time_t t2);

difftime takes two calendar times, and returns their difference in seconds, which is positive if t1 is a later time than t2, as if the function is subtracting t2 from t1.

<time.h> also defines a type struct tm, which contains various members describing a calendar time in the Gregorian calendar, according to some timezone:

Members of `struct tm`
Field	Meaning
`int tm_sec`	Seconds after the minute
`int tm_min`	Minutes after the hour
`int tm_hour`	Hours since midnight
`int tm_mday`	Day of the month
`int tm_mon`	Months since January
`int tm_year`	Years since 1900
`int tm_wday`	Days since Sunday
`int tm_yday`	Days since the 1^st of January
`int tm_isdst`	“Daylight Saving Time” flag (0⇒false; 1⇒true; <0⇒unavailable)

#include <time.h>
struct tm *gmtime(const time_t *tp);
struct tm *localtime(const time_t *tp);

#include <time.h>
#define __STDC_WANT_LIB_EXT1__ 1
struct tm *gmtime_s(const time_t *tp, struct tm *sp);
struct tm *localtime_s(const time_t *tp, struct tm *sp);

These functions break a calender time *tp into a Gregorian time as a struct tm. The gmtime functions report the time according to UTC, while the localtime functions use a local timezone. gmtime and localtime return a pointer to some internal struct tm which has static storage duration, and could be overwritten by subsequent calls. gmtime_s and localtime_s take a pointer to a struct tm, set its fields to represent the Gregorian time, and then return the same pointer. All functions return NULL if the time cannot be converted. The _s functions also return NULL if any of the arguments are NULL.

Structural calendar times can be converted to strings using functions such as strftime.

#include <time.h>
time_t mktime(struct tm *tp);

mktime converts a local time *tp into arithmetic form, and returns it.

There does not appear to be any portable way to convert a UTC time into arithmetic time.