Date and Time Conversion Functions in C

Answer: We know that ‘time()’ function returns value of type ‘time_t’ which is a 32-bit signed value on many implementations. The value returned is no. of seconds from some arbitrary epoch, for ex. 00:00:00 January 1, 2014. In order to obtain current date and time of the day, we need to manipulate this value. Date and Time conversion functions prototyped below manipulate this value,

    char *ctime(time_t const *time_value);
    double difftime(time_t tm1, time_t tm2);

‘ctime()’ takes pointer-to-time_t, converts it and returns string. This outputs as

current date and time of the day: Thu Jul  3 19:03:56 2014

‘ctime()’, actually, may be implemented as ‘asctime()’ function which is prototyped as below

    char *asctime(localtime(time_value));

Notice that ‘asctime()’ receives ‘localtime()’ as an argument. Therefore, let’s first understand this

    struct tm *localtime(time_t const *time_value);

Observe that ‘localtime()’ function takes a time value and converts it into local time i.e. it takes pointer-to-time_t and returns pointer-to-time structure. Reference of this structure is then passed to ‘asctime()’ function which returns character string specifying current date and time of day. I included fragment of code below, from ‘time.h’ header to specify different fields in structure of type ‘struct tm’.

struct tm
{
  int tm_sec;                   /* Seconds.     [0-60] (1 leap second) */
  int tm_min;                   /* Minutes.     [0-59] */
  int tm_hour;                  /* Hours.       [0-23] */
  int tm_mday;                  /* Day.         [1-31] */
  int tm_mon;                   /* Month.       [0-11] */
  int tm_year;                  /* Year - 1900.  */
  int tm_wday;                  /* Day of week. [0-6] */
  int tm_yday;                  /* Days in year.[0-365] */
  int tm_isdst;                 /* DST.         [-1/0/1]*/
 
};

There’s one more function which converts ‘time_t’ value into ‘struct tm’. This is prototyped as below

    struct tm *gmtime(time_t const *time_value);

‘gmtime()’ function converts time value into Coordinated Universal Time (UTC). UTC was formerly called Greenwich Mean Time and hence the name gmtime. Note here that though standard includes both functions but doesn’t specify how relationship between UTC and local time is to be implemented.

Major benefit of the time structure ‘tm’ returned as function value is that it allows us directly access to its different fields. Or you can pass it as an argument to other functions, for ex.

    char *asctime(struct tm const *tm_ptr);
    size_t strftime(char *string, size_t maxsize, char const *format,
                        struct tm const *tm_ptr);

Notice that ‘asctime()’ outputs same as ‘ctime()’. ‘ctime()’ may actually call ‘asctime()’ to perform it’s work. ‘strftime()’ converts structure of type ‘struct tm’ into a character string according to format string. This function provides tremendous flexibility in formatting dates. Notice that if the resulting string is less than maxsize, then it’s copied into array the first argument points to and function returns length of string otherwise contents of string are undefined and function returns 0.

Let’s, finally, consider a function which is used to convert a struct ‘tm’ into ‘time_t’ value. It’s prototype is given below

    time_t mktime(struct tm *tm_ptr);

The values ‘tm_wday’ (days after Sunday), ‘tm_yday’ (days after January 1) in struct ‘tm’ are ignored and values in other fields need not be within their usual ranges. After the conversion, struct tm is then normalized, so that ‘tm_wday’ and ‘tm_yday’ are correct and remaining fields are well within their usual ranges.