Date/Time Basics

A calendar time is a point in the time continuum, for example November 4, 1990 at 18:02.5 UTC. Sometimes this is called “absolute time”. We don't speak of a “date”, because that is inherent in a calendar time. An interval is a contiguous part of the time continuum between two calendar times, for example the hour between 9:00 and 10:00 on July 4, 1980. An elapsed time is the length of an interval, for example, 35 minutes. People sometimes sloppily use the word “interval” to refer to the elapsed time of some interval. An amount of time is a sum of elapsed times, which need not be of any specific intervals. For example, the amount of time it takes to read a book might be 9 hours, independently of when and in how many sittings it is read.

A period is the elapsed time of an interval between two events, especially when they are part of a sequence of regularly repeating events. CPU time is like calendar time, except that it is based on the subset of the time continuum when a particular process is actively using a CPU. CPU time is, therefore, relative to a process. Processor time is an amount of time that a CPU is in use. In fact, it's a basic system resource, since there's a limit to how much can exist in any given interval (that limit is the elapsed time of the interval times the number of CPUs in the processor). People often call this CPU time, but we reserve the latter term in this manual for the definition above.

Calendar Time

We can represent calendar time two ways:

• Simple time (the time_t data type) is a compact representation, typically giving the number of seconds of elapsed time since some implementation-specific base time.

• Local time or broken-down time (the struct tm data type) represents a calendar time as a set of components specifying the year, month, and so on in the Gregorian calendar, for a specific time zone. This calendar time representation is usually used only to communicate with people.

The relationship among the various time data types and functions is shown in the following diagram.

Dashed lines show functions that are affected by the time zone (TZ) environment variable

Simple Calendar Time

#include <time.h> time_t time (time_t *result)

The time function returns the current calendar time as a value of type time_t. If the argument result is not a null pointer, the calendar time value is also stored in *result. If the current calendar time is not available, the value (time_t)(-1) is returned.

The data type time_t is used to represent simple time. Sometimes, it also represents an elapsed time. When interpreted as a calendar time value, it represents the number of seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal Time. (This calendar time is sometimes referred to as the epoch.)

Note that a simple time has no concept of local time zone. Calendar Time T is the same instant in time regardless of where on the globe the computer is.

Broken-down Time

Broken-down time is a binary representation of calendar time separated into year, month, day, and so on. Broken-down time values are not useful for calculations, but they are useful for printing human readable time information.

A broken-down time value is always relative to a choice of time zone.

The data type struct tm (declared in the header file time.h) is used to represent a broken-down time. The structure contains at least the following members, which can appear in any order.

Members	Description
int tm_sec	This is the number of full seconds since the top of the minute (normally in the range 0 through 59, but the actual upper limit is 60, to allow for leap seconds if leap second support is available).
int tm_min	This is the number of full minutes since the top of the hour (in the range 0 through 59).
int tm_hour	This is the number of full hours past midnight (in the range 0 through 23).
int tm_mday	This is the ordinal day of the month (in the range 1 through 31). Watch out for this one! As the only ordinal number in the structure, it is inconsistent with the rest of the structure.
int tm_mon	This is the number of full calendar months since the beginning of the year (in the range 0 through 11). Watch out for this one! People usually use ordinal numbers for month-of-year (where January = 1).
int tm_year	This is the number of full calendar years since 1900.
int tm_wday	This is the number of full days since Sunday (in the range 0 through 6).
int tm_yday	This is the number of full days since the beginning of the year (in the range 0 through 365).
int tm_isdst	This is a flag that indicates whether Daylight Saving Time is (or was, or will be) in effect at the time described. The value is positive if Daylight Saving Time is in effect, zero if it is not, and negative if the information is not available.

Conversion between Calendar Time and Broken-down Time

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

Formatting Calendar Time

The functions described in this section format calendar time values as strings.

#include <time.h> char * asctime (const struct tm *brokentime) char * ctime (const time_t *time) size_t strftime (char *s, size_t size, const char *template, const struct tm *brokentime)

Code	Description	Example
%a	abbreviated weekday name	Tue
%A	full weekday name	Tuesday
%b	abbreviated month name	Feb
%B	full month name	February
%c	date and time	Tue Feb 10 18:27:39 2004
%C	century (year/100)	20
%d	day of the month (01 through 31)	10
%D	date (%m/%d/%y)	02/10/04
%e	day of the month padded with blank (range 1 through 31)	10
%F	ISO 8601 date u format %Y-%m-%d.	2004-02-10
%g	last two digits of ISO 8601 week-based year	04
%G	ISO 8601 week-based year	2004
%h	abbreviated month name(same as %b)	Feb
%H	hour of the day (24-hour clock) [00 through 23]	18
%I	hour of the day (12-hour clock) [01 through 12]	06
%j	day of the year [001 through 366]	041
%m	month [01 through 12]	02
%M	minute [ 00 through 59]	27
%n	(newline) character (\n)
%p	AM or PM. Noon is PM	PM
%r	locale's time (12-hour clock)	06:27:38 PM
%R	same as %H:%M	18:27
%S	seconds [ 00 through 60]	38
%t	horizontal tab character \t
%T	same as %H:%M:%S	18:27:38
%u	ISO weekday [1 through 7], Monday being 1	2
%U	Sunday week number [ 00 through 53]	06
%V	ISO 8601 week number [ 01 through 53]	07
%w	week day [ 0 through 6], Sunday being 0	2
%W	Monday week number[00 through 53]	06
%x	date	02/10/04
%X	time	18:27:38
%y	last two digits of year [ 00 through 99]	04
%Y	year	2004
%z	offset from UTC in ISO format	-0500
%Z	The time zone abbreviation	EST
%%	translates to a percent sign	%

References

Maintained by John Loomis, last updated 6 September 2006