# Chapter 12. Date and Time <time.h>

12.1. Time Manipulation Functions
12.2. Time Conversion Functions

The header <time.h> defines two macros, declares four types and several functions for manipulating time. Many functions deal with a calendar time that represents the current date (according to the Gregorian calendar) and time. Some functions deal with local time, which is the calendar time expressed for some specific time zone, and with Daylight Saving Time, which is a temporary change to the algorithm for determining local time. The local time zone and Daylight Saving Time are implementation-defined.

The macros defined are NULL (described in ANSI C 7.1.6); and CLOCKS_PER_SEC which is the number per second of the value returned by the clock function.

The types declared are size_t (described in ANSI C 7.1.6), clock_t and time_t, which are arithmetic types capable of representing times, and struct tm which holds components of a calendar time, called the broken-down time.

The structure struct tm is defined as follows:

```struct tm
{
int tm_sec;    /* seconds after the minute [0,61] */
int tm_min;    /* minutes after the hour [0,59]   */
int tm_hour;   /* hour of the day [0,23]          */
int tm_mday;   /* day of the month [1,31]         */
int tm_mon;    /* month of the year [0,11]        */
int tm_year;   /* years since 1900                */
int tm_wday;   /* days since Sunday [0,6]         */
int tm_yday;   /* day of the year [0,365]         */
int tm_isdst;  /* Daylight Saving Time flag       */
};
```

The member tm_isdst is:

• positive if Daylight Saving Time is in effect

• zero if Daylight Saving Time is not in effect

• negative if the information is not available

# 12.1. Time Manipulation Functions

## 12.1.1. The clock function

##### Synopsis
```#include <time.h>
```

```clock_t clock ( void );```

##### Description

The clock function determines the processor time used.

##### Returns

The clock function returns the implementation's best approximation to the processor time used by the program since the beginning of an implementation-defined era related only to the program invocation. To determine the time in seconds, the value returned by the clock function should be divided by the value of the macro CLOCKS_PER_SEC. If the processor time used is not available or its value cannot be represented, then the function returns the value (clock_t)-1.

##### Implementation Notes
• The value of CLOCKS_PER_SEC is 100 by default.

• The value of the function clock is zero immediately after the run-time system is started or restarted.

• The processor time to wall time ratio is 1:1 while the processor is running.

## 12.1.2. The difftime function

##### Synopsis
```#include <time.h>
```

```double difftime (time_t time1 , time_t time0 );```

##### Description

The difftime function computes the difference between two calendar times: time1 - time0.

##### Returns

The difftime function returns the difference expressed in seconds as a double.

## 12.1.3. The mktime function

##### Synopsis
```#include <time.h>
```

```time_t mktime (struct tm * timeptr );```

##### Description

The mktime function converts the broken-down time, expressed as local time, in the structure pointed to by timeptr into a calendar time with the same encoding as that of the values returned by the time function. The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values of other components are not restricted to the ranges indicated above. On successful completion, the values of the tm_wday and tm_yday components of the structure are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to the ranges indicated above; the final value of tm_day is not set until tm_mon and tm_year are determined.

##### Returns

The mktime function returns the specified calendar time encoded as a value of the type time_t. If the calendar time cannot be represented, the function returns the value (time_t)-1.

## 12.1.4. The time function

##### Synopsis
```#include <time.h>
```

```time_t time (time_t * timer );```

##### Description

The time function determines the current calendar time. The encoding of the value is unspecified.

##### Returns

The time function returns the implementation's best approximation to the current calendar time. The value (time_t)-1 is returned if the calendar time is not available. If timer is not a null pointer, then the return value is also assigned to the object it points to.

##### Implementation Notes
• The current calendar time is held in the run-time system with a resolution of 1 second and a range of 2**32 seconds, or 136 years.

• Calendar time is reset to zero each time the run-time system is restarted, where time zero is 00:00:00 on Thursday January 1, 1970.