What are date and time utilities in C?
The time.h header defines a group of useful functions and constants in order to perform date and time manipulations. The time.h header is part of the C standard libray and supports for time conversion, acquisition, and manipulation.
Types
Type | Description |
clock_t | stores the clock ticks used by the processor |
size_t | unsigned integer type |
time_t | stores values of time |
struct tm | a structure with member variables to store date and time in calendar format |
A complete description of types in the time.h header can be
Constants
Constant | Description |
CLOCKS_PER_SEC | represents the number of CPU clock ticks per second |
Time manipulation
difftime()
difftime()returns the difference between two time values.
Prototype
double difftime (time_t end, time_t beginning);
Parameters
end: the upper value of the time intervalbeginning: the lower value for the time interval
Return Value
- Return type:
double
difftime() returns the difference in time between beginning and end.
clock()
clock() returns processor time utilized by the process in the form of the number of clock ticks elapsed since the start of the process.
Prototype
clock_t clock (void);
Parameters
- None
Return Value
- Return type:
clock_t
time()
time()returns the current time as a value of typetime_t.
Prototype
time_t time (time_t* timer);
Parameters:
- A pointer to the
time_tvariable where the value of the current time is stored. (optional) - If a
NULLpointer is passed, the argument is not used and the current time is returned.
Return Value
- Return type:
clock_t
Example code
#include <stdio.h>#include <time.h>#include <unistd.h>int main(void){//Processor Ticksclock_t start_ticks = clock();clock_t end_ticks = clock();printf("start_ticks = %li\nend_ticks = %li\n", start_ticks, end_ticks);//Timetime_t end_time;time_t start_time = time(NULL);sleep(1);time(&end_time);printf("start_time = %lis\nend_time = %lis\n", start_time, end_time);//Differencedouble interval = difftime(end_time, start_time);printf("difference = %fs\n", interval);}
The code above shows an example of how to use the time manipulation functions provided in the time.h header.
The CPU ticks are provided by the clock() function and are stored in the start_ticks and end_ticks variables of type clock_t.
The time values are stored in start_time and end_time which are variables of type time_t. We first pass a NULL pointer to the time() function which returns the starting time.
time_t start_time = time(NULL);
The time() function also allows us to store the value of time by passing a pointer to a time_t variable as shown below.
time_t end_time;
time(&end_time);
Finally, the difftime() function calculates the difference between the start_time and the end_time and returns it as a double.
Time Conversions
mktime()
mktime() returns the local time represented by a tm structure. If some values in the tm structure are out of range, then mktime() automatically adjusts time accordingly. For example, tm.mday may contain values greater than 31, which will be interpreted as the number of days after the selected month.
Prototype
time_t mktime (struct tm * timeptr);
Parameters
timeptr: A pointer to thetmstructure that needs to be converted to a value represented intime_t.
Return Value
- Return type:
time_t
mktime() returns the time_t representation of the tm structure pointed to by the timeptr pointer.
localtime()
localtime() converts the time represented by the type time_t to the equivalent representation as a tm struct.
Prototype
struct tm * localtime (const time_t * timer);
Parameters
timer: A pointer to the variable of typetime_tthat represents the time since epoch.
Return Value
- Return type: Pointer to a
struct tmthat corresponds with thelocaltimerepresented bytimer
gmtime()
gmtime() converts the time pointed by the timer pointer of the type time_t*.
Prototype
struct tm * gmtime (const time_t * timer);
Parameters
timer: A pointer to the variable of typetime_tthat represents the local time as the number of seconds elapsed since epoch.
Return Value
- Return type: Pointer to a
struct tmthat corresponds with the localtime represented bytimer
ctime()
ctime() converts the time pointed by timer into a string representing the calendar time.
Prototype
char* ctime (const time_t * timer);
Parameters
timer: A pointer to the variable of typetime_tthat represents the local time as the number of seconds elapsed since epoch.
Return Value
- Return type: A pointer to the
chararray that contains the string representation of local time pointed by thetimerpointer.
asctime()
asctime() converts the time in the tm struct pointed to by timeptr into a readable string representation.
Prototype
char* asctime (const struct tm * timeptr);
Parameters
timer: A pointer to the variable of typestruct tmthat represents the local time.
Return Value
- Return type: A pointer to the
chararray that contains the string representation of local time pointed by thetimeptrpointer.
Example
#include <stdio.h>#include <time.h>int main(void){//get current time in seconds since epochtime_t now;now = time(NULL);struct tm * local_time, * gmt_time;// get local time in struct tmlocal_time = localtime(&now);//convert to GMTgmt_time = gmtime(&now);//convert struct tm to its string representationchar* time_as_string = asctime(gmt_time);printf("UTC time converted from struct tm to string: %s", time_as_string);//convert GMT time back to time_ttime_t time = mktime(gmt_time);//convert time to stringchar* time_as_string_2 = ctime(&time);printf("UTC time converted from time_t to string: %s", time_as_string_2);}
strftime()
strftime() converts the time in the tm struct pointed to by timeptr into a readable string representation.
Prototype
size_t strftime (char* ptr, size_t maxsize, const char* format,
const struct tm* timeptr );
Parameters
ptr: A pointer to the destination array where the resultant string is copied into.maxsize: Maximum number of characters to be copied intoptr, including thenull-termination characterformat: Pointer to the C-string containing any number of format specifiers and regular characters. Format specifiers are distinguished by a preceding “%” sign.
Format Specifier | Replaced by |
%a | Abbreviated weekday name |
%A | Full weekday name |
%b | Abbreviated month name |
%B | Full month name |
%c | Date and Time representation |
%C | Year divided by 100 (truncated to the nearest integer) |
A full list of format specifiers is available here
Return Value
- Return type:
size_t - Returns the number of characters copied into
ptrarray. If the number of characters exceeds themaxsize, then it returns 0.
Example Code
First, we create a destination array of size 80 characters. Then, we copy the string representation of the date in the dest array using the following code:
strftime(dest, maxsize, "%D", time_struct);
The format specifier %D represents the current date.
#include <stdio.h>#include <time.h>int main(void){size_t maxsize = 80;char dest[maxsize];struct tm * time_struct;time_t now;time(&now);time_struct = localtime(&now);strftime(dest, maxsize, "%D", time_struct);printf("Today's date: %s\n", dest);}
Free Resources
