mktime(3C)

NAME

     mktime - converts a tm structure to a calendar time

SYNOPSIS

     #include <time.h>

     time_t mktime(struct tm *timeptr);

DESCRIPTION

     The mktime() function converts the time represented  by  the
     tm  structure  pointed  to  by  timeptr into a calendar time
     (the number of seconds since 00:00:00 UTC, January 1, 1970).

     The tm structure contains the following members:

     int  tm_sec;     /* seconds after the minute [0, 61]  */
     int  tm_min;     /* minutes after the hour [0, 59] */
     int  tm_hour;    /* hour since midnight [0, 23] */
     int  tm_mday;    /* day of the month [1, 31] */
     int  tm_mon;     /* months since January [0, 11] */
     int  tm_year;    /* years since 1900 */
     int  tm_wday;    /* days since Sunday [0, 6] */
     int  tm_yday;    /* days since January 1 [0, 365] */
     int  tm_isdst;   /* flag for daylight savings time */

     In addition to computing the calendar time, mktime() normal-
     izes  the  supplied tm structure. The original values of the
     tm_wday and tm_yday components of the structure are ignored,
     and the original values of the other components are not res-
     tricted to the ranges indicated in  the  definition  of  the
     structure.  On  successful  completion,  the  values  of the
     tm_wday and tm_yday components are  set  appropriately,  and
     the  other  components  are  set  to represent the specified
     calendar time, but with their values forced to be within the
     appropriate  ranges.  The  final value of tm_mday is not set
     until tm_mon and tm_year are determined.

     The tm_year member must be for year 1901 or later.  Calendar
     times  before  20:45:52  UTC,  December  13,  1901  or after
     03:14:07 UTC,  January 19, 2038 cannot be represented. Port-
     able  applications  should  not  try  to create dates before
     00:00:00 UTC, January 1, 1970 or after 00:00:00 UTC, January
     1, 2038.

     The original values of the components may be either  greater
     than  or  less  than  the  specified  range.  For example, a
     tm_hour of -1 means 1 hour before  midnight,  tm_mday  of  0
     means  the day preceding the current month, and tm_mon of -2
     means 2 months before January of tm_year.

     If tm_isdst is positive, the original values are assumed  to
     be  in  the  alternate  timezone.  If  it turns out that the
     alternate timezone is not valid for  the  computed  calendar
     time, then the components are adjusted to the main timezone.
     Likewise, if tm_isdst  is  zero,  the  original  values  are
     assumed  to be in the main timezone and are converted to the
     alternate timezone if the main timezone  is  not  valid.  If
     tm_isdst is negative, mktime() attempts to determine whether
     the alternate timezone is in effect for the specified time.

     Local timezone information is used as if mktime() had called
     tzset(). See ctime(3C).

RETURN VALUES

     If the calendar time can be represented in an object of type
     time_t, mktime() returns the specified calendar time without
     changing errno. If the calendar time cannot be  represented,
     the  function returns the value (time_t)-1 and sets errno to
     indicate the error.

ERRORS

     The mktime() function will fail if:

     EOVERFLOW
           The date represented by the input tm struct cannot  be
           represented  in a time_t.  Note that the errno setting
           may  change  if  future  revisions  to  the  standards
           specify a different value.

USAGE

     The  mktime() function is MT-Safe in multithreaded  applica-
     tions, as long as no user-defined function directly modifies
     one of the following variables: timezone, altzone, daylight,
     and tzname. See ctime(3C).

     Note that -1 can be a valid return value for the  time  that
     is one second before the Epoch.  The user should clear errno
     before calling mktime(). If mktime() then  returns  -1,  the
     user should check errno to determine whether or not an error
     actually occurred.

     The  mktime() function assumes Gregorian dates. Times before
     the  adoption  of the Gregorian calendar will not match his-
     torial records.

EXAMPLES

     Example 1: Sample code using mktime().

     What day of the week is July 4, 2001?

     #include <stdio.h>
     #include <time.h>
     static char *const wday[] = {
             "Sunday", "Monday", "Tuesday", "Wednesday",
             "Thursday", "Friday", "Saturday", "-unknown-"
     };
     struct tm time_str;
     /*...*/
     time_str.tm_year    = 2001 - 1900;
     time_str.tm_mon = 7 - 1;
     time_str.tm_mday = 4;
     time_str.tm_hour = 0;
     time_str.tm_min = 0;
     time_str.tm_sec = 1;
     time_str.tm_isdst = -1;
     if (mktime(&time_str)== -1)
             time_str.tm_wday=7;
     printf("%s\n", wday[time_str.tm_wday]);

BUGS

     The zoneinfo timezone data files do not transition past  Tue
     Jan 19 03:14:07 2038 UTC.  Therefore for 64-bit applications
     using zoneinfo timezones, calculations beyond this date  may
     not  use  the  correct  offset from standard time, and could
     return incorrect values.
      This affects the 64-bit version of mktime().

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | MT-Safe with exceptions     |
    |_____________________________|_____________________________|

SEE ALSO

     ctime(3C), getenv(3C), TIMEZONE(4), attributes(5)