How do I use the C date and time functions on UNIX?

Question

Jon Skeet spoke of the complexity of programming dates and times at the 2009 DevDays in London.

Can you give me an introduction to the ANSI C date/time functions on UNIX and indicate some of the deeper issues I should also consider when using dates and times?

Answer 1

Terminology

A date/time can be in two formats:

• calendar time (a.k.a. simpletime) – time as an absolute value typically since some base time, often referred to as the Coordinated Universal Time
• localtime (a.k.a. broken-down time) – a calendar time made up of components of year, month, day etc. which takes into account the local time zone including Daylight Saving Time if applicable.

Data types

The date/time functions and types are declared in the time.h header file.

Time can be stored as a whole number or as an instance of a structure:

• as a number using the time_t arithmetic type – to store calendar time as the number of seconds elapsed since the UNIX epoch January 1, 1970 00:00:00

• using the structure timeval – to store calendar time as the number of seconds and nanoseconds elapsed since the UNIX epoch January 1, 1970 00:00:00

• using the structure tm to store localtime, it contains attributes such as the following:

  tm_hour  
  tm_min  
  tm_isdst
  

The tm_isdst attribute above is used to indicate Daylight Saving Time (DST). If the value is positive it is DST, if the value is 0 it is not DST.

Program to print the current Coordinated Universal Time

#include <stdio.h>
#include <time.h>

int main ( int argc, char *argv[] )
{
    time_t now;

    now = time ( NULL );

    printf ( “It’s %ld seconds since January 1, 1970 00:00:00”, (long) now );

    return 0;
}

In the program above the function time reads the UNIX system time, subtracts that from January 1, 1970 00:00:00 (the UNIX epoch) and returns its result in seconds.

Program to print the current local time

#include <stdio.h>
#include <time.h>

int main ( int argc, char *argv[] )
{
    time_t now;
    struct tm *lcltime;

    now = time ( NULL );
    lcltime = localtime ( &now );

    printf ( “The time is %d:%d\n”, lcltime->tm_hour, lcltime->tm_min );

    return 0;
}

In the program above the function localtime converts the elapsed time in seconds from the UNIX epoch into the broken-down time. localtime reads the UNIX environment TZ (through a call to the tzset function) to return the time relative to the timezone and to set the tm_isdst attribute.

A typical setting of the TZ variable in UNIX (using bash) would be as follows:

export TZ=GMT

or

export TZ=US/Eastern

Program to print the current formatted Greenwich Mean Time

#include <stdio.h>
#include <time.h>

int main ( int argc, char *argv[] )
{
    time_t now;
    struct tm *gmt;
    char formatted_gmt [50];

    now = time ( NULL );
    gmt = gmtime ( &now );

    strftime ( formatted_gmt, sizeof(formatted_gmt), "%I:%M %p”, gmt );
    printf ( “The time is %s\n”, formatted_gmt );

    return 0;
}

In the program above the function strftime provides specialised formatting of dates.

Other issues to consider

• Leap seconds
• What should we do to prepare for 2038?