mktime

mktime

Generate Encoded Time Value

Portability: ISO/ANSI C conforming, UNIX compatible, POSIX.1 conforming

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <time.h>

time_t mktime(struct tm *timeinfo);

DESCRIPTION

mktime converts a date and time (expressed as a struct tm value) into a time_t value. Although the struct tm type is convenient for input and output, it is difficult to compare or subtract time values of this type.

The time_t type is an alternate time format; it can be difficult to interpret directly, but it has compensating advantages. Notably, it is easy to compare two time_t values or to subtract them using the difftime function. You can use the mktime function to obtain a time_t value from a struct tm value; the opposite conversion is performed by the localtime routine.

The timeinfo argument is a pointer to the struct tm value to be converted. The value is assumed to represent local time, not Greenwich Mean Time. mktime is affected by time-zone information contained in the TZ environment variable, if it is defined.

The components of the struct tm value to be converted are not required to fall within their normal ranges. (See Timing Functions for information on these ranges.) If any components of the value pointed to by timeinfo are out of range, they are adjusted appropriately before conversion. The tm_wday and tm_yday components of the value pointed to by timeinfo are ignored by mktime but are always set appropriately when it returns.

You can use mktime to perform arithmetic on dates and times. For example, to determine the date and time 1,000,000 seconds from a given time, add 1,000,000 to the seconds component of the time ( tm_sec ) and pass its address to mktime . On return from mktime , the time value is adjusted to contain accurate information.

mktime handles the tm_isdst field of the timeinfo argument differently, depending on whether the TZ environment variable has been set. TZ may be defined in three ways:

TZ is defined completely (that is, it defines both a standard time offset and a Daylight Savings Time (DST) offset).: In this case, if tm_isdst is zero, the time is assumed to be expressed relative to standard time; if tm_isdst is 1, the time is relative to DST. If tm_isdst is negative, the appropriate setting is determined. In either case, tm_isdst is set on return to indicate whether DST was in effect for the actual time specified. If is_dst is -1, it is possible to specify an impossible time, namely one that is skipped over in the transition between standard time and DST. In this case, mktime fails and returns -1.
TZ only defines a standard time offset.: In this case, if tm_isdst is positive, mktime fails and returns -1. Otherwise, standard time is assumed, and tm_isdst is set to 0 on return.
TZ is not defined.: In this case, it is impossible to determine whether standard time or DST is in effect. tm_isdst is set to -1 on return; if it was not negative on entry, a diagnostic is generated. The offset from Greenwich Mean Time is based on the assumption that the hardware TOD clock reflects Greenwich Mean Time. Except for the warning if tm_isdst is nonnegative, this behavior is compatible with prior releases of SAS/C.

RETURN VALUE

mktime returns an encoded time value that corresponds to the input argument. If the argument cannot be converted, -1 is returned.

CAUTION

If the argument to mktime specifies a value outside the range of the IBM 370 time-of-day clock (between the years 1900 and 2041), the value returned is unpredictable.

EXAMPLE

This example computes the number of days until Christmas, using mktime :

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

main()
{
   time_t now;
   static struct tm today, xmas = {0};
   time_t xmas_time;

      /* Get today's date and time (encoded).    */
   time(&now);

      /* Break into components.                  */   
   today = *localtime(&now);   

      /* Build midnight Christmas time structure */
      /*  for this year.                         */
   xmas.tm_mday  = 25;
   xmas.tm_mon   = 11;
   xmas.tm_year  = today.tm_year;
   xmas.tm_isdst = -1;

      /* Get encoded Christmas time.             */
   xmas_time = mktime(&xmas);

      /* Convert seconds to days and print.      */
   printf("Only %d days until Christmas.\n",
         (int)(difftime(xmas_time, now) / 86400.0));
}

RELATED FUNCTIONS

localtime , tzset

SEE ALSO

Timing Functions

Chapter Contents
Previous
Next
Top of Page