mktime() — Convert Local Time

Standards / Extensions	C or C++	Dependencies
ISO C POSIX.1 XPG4 XPG4.2	both

Format

#include <time.h>

time_t mktime(struct tm *tmptr);

General Description

Converts broken-down time, expressed as a local time, in the tm structure pointed to by tmptr, to calendar time. Calendar time is the number of seconds since epoch, which was at 00:00:00 January 1, 1970.

The tm structure is described in Table 1.

The values of the structure members passed to mktime() are not restricted to the ranges described in gmtime() — Convert Time to Broken-Down UTC Time. The mktime() function ignores the values of tm_wday and tm_yday and assigns their correct values on return.

If successful, mktime() sets all the members of the structure pointed to by time to represent the specified time with their values forced into the ranges described in gmtime() — Convert Time to Broken-Down UTC Time. The function sets the values of tm_wday after it determines the values of tm_mon and tm_year.

If an application uses localtime() to determine local time, localtime() will determine if daylight savings applies (assuming DST info is available) and will correctly set the tm_isdst flag. If the application wants to determine seconds from Epoch corresponding to a tm structure returned by localtime(), it should not modify the tm_isdst flag set by localtime().

If an application sets tm_isdst = 0 before calling mktime(), it is asserting that daylight savings does not apply, regardless of the system DST start and end dates. Likewise, if the application has set a value for tm_isdst to be greater than 0, it is asserting that the time represented by the tm structure has been shifted for daylight savings. Therefore, mktime() unshifts the time in determining seconds since Epoch.

Setting tm_isdst to -1 tells the mktime() function to determine whether daylight savings time applies. If so, mktime() returns tm_isdst greater than 0. If not, it returns tm_isdst of 0 unless DST information is not available on the system, in which case mktime() returns tm_isdst of -1.

Your time zone may not be using a Daylight Savings Time, perhaps because the TZ environment variable does not specify a daylight savings time name or perhaps because DSTNAME is unspecified in the current LC_TOD locale category. In such a case, if you code tm_isdst=1 and call mktime(), the function returns (time-t)-1 to indicate an error.

Note: The mktime() function is sensitive to time zone information, which is provided by:

The TZ environmental variable when POSIX(ON) and TZ is correctly defined, or by the _TZ environmental variable when POSIX(OFF) and _TZ is correctly defined.
The LC_TOD category of the current locale if POSIX(OFF) or TZ is not defined.

The time zone external variables tzname, timezone, and daylight declarations remain feature test protected in time.h.

For more information about using POSIX support, see IBM XL C/C++ for z/VM Applications with OpenExtensions Services.

Returned Value

Returns the calendar time corresponding to broken-down time, expressed as local time, using the tm structure, which is pointed to by tmptr. If mktime() cannot convert the broken-down time to a calendar time, it returns (time_t)-1 to indicate an error, such as time before January 1, 1970.

The ctime(), localtime(), and mktime() functions now return coordinated, unless customized locale information is made available, which includes setting the timezone_name variable.
In POSIX you can supply the necessary information by using environment variables.
In non-POSIX applications, you can supply customized locale information by setting time zone and daylight information in LC_TOD.
By customizing the locale, you allow the time functions to preserve both time and date, correctly adjusting for daylight time on a given date.

Example

CBC3BM19

/* CBC3BM19
   This example prints the day of the week that is 40 days and 16 hours
   from the current date.
 */
#include <stdio.h>
#include <time.h>

char *wday[] = { "Sunday", "Monday", "Tuesday", "Wednesday",
                 "Thursday", "Friday", "Saturday" };

int main(void)
{
  time_t t1, t3;
  struct tm *t2;

  t1 = time(NULL);
  t2 = localtime(&t1);
  t2 -> tm_mday += 40;
  t2 -> tm_hour += 16;
  t3 = mktime(t2);

  printf("40 days and 16 hours from now, it will be a %s \n",
          wday[t2 -> tm_wday]);
}

Output

40 days and 16 hours from now, it will be a Sunday