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 foundhttps://cplusplus.com/reference/ctime/strftime/.

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 interval
  • beginning: 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 type time_t.

Prototype

time_t time (time_t* timer);

Parameters:

  • A pointer to the time_t variable where the value of the current time is stored. (optional)
  • If a NULL pointer 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 Ticks
    clock_t start_ticks = clock();
    clock_t end_ticks = clock();  
    printf("start_ticks = %li\nend_ticks   = %li\n", start_ticks, end_ticks);
    
    //Time
    time_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);
    //Difference
    double 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 the tm structure that needs to be converted to a value represented in time_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 type time_t that represents the time since epoch.

Return Value

  • Return type: Pointer to a struct tm that corresponds with the localtime represented by timer

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 type time_t that represents the local time as the number of seconds elapsed since epoch.

Return Value

  • Return type: Pointer to a struct tm that corresponds with the localtime represented by timer

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 type time_t that represents the local time as the number of seconds elapsed since epoch.

Return Value

  • Return type: A pointer to the char array that contains the string representation of local time pointed by the timer pointer.

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 type struct tm that represents the local time.

Return Value

  • Return type: A pointer to the char array that contains the string representation of local time pointed by the timeptr pointer.

Example

#include <stdio.h>
#include <time.h>
int main(void){  
    //get current time in seconds since epoch
    time_t now;
    now = time(NULL);
    struct tm * local_time, * gmt_time;
    // get local time in struct tm
    local_time = localtime(&now);
    //convert to GMT
    gmt_time   = gmtime(&now);
    //convert struct tm to its string representation
    char* 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_t
    time_t time = mktime(gmt_time);
    //convert time to string
    char* 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 into ptr, including the null-termination character
  • format: 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 ptr array. If the number of characters exceeds the maxsize, 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

Copyright ©2026 Educative, Inc. All rights reserved