localtime(3) - NetBSD Manual Pages

CTIME(3)                                                 CTIME(3)



NAME

       asctime, ctime, difftime, gmtime, localtime, mktime - con-
       vert date and time to ASCII


SYNOPSIS

       #include <time.h>

       extern char *tzname[2];

       void tzset()

       #include <sys/types.h>

       char *ctime(clock)
       const time_t *clock;

       double difftime(time1, time0)
       time_t time1;
       time_t time0;

       char *asctime(tm)
       const struct tm *tm;

       struct tm *localtime(clock)
       const time_t *clock;

       struct tm *gmtime(clock)
       const time_t *clock;

       time_t mktime(tm)
       struct tm *tm;



DESCRIPTION

       Ctime converts a long integer, pointed to by clock, repre-
       senting   the   time   in   seconds  since  00:00:00  UTC,
       1970-01-01, and returns a pointer to a 26-character string
       of the form
                      Thu Nov 24 18:22:48 1986\n\0
       All the fields have constant width.

       Localtime and gmtime return pointers to ``tm'' structures,
       described below.  Localtime corrects for the time zone and
       any time zone adjustments (such as Daylight Saving Time in
       the U.S.A.).   After  filling  in  the  ``tm''  structure,
       localtime  sets  the  tm_isdst'th  element  of tzname to a
       pointer to an ASCII string that's the time zone  abbrevia-
       tion to be used with localtime's return value.

       Gmtime converts to Coordinated Universal Time.

       Asctime converts a time value contained in a ``tm'' struc-
       ture to a 26-character string, as shown in the above exam-
       ple, and returns a pointer to the string.



                                                                1





CTIME(3)                                                 CTIME(3)


       Mktime  converts  the broken-down time, expressed as local
       time, in the structure pointed to by tm  into  a  calendar
       time  value  with  the same encoding as that of the values
       returned by the time function.  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 restricted to their normal ranges.  (A positive or
       zero value for tm_isdst causes mktime to presume initially
       that summer time (for example, Daylight Saving Time in the
       U.S.A.)  respectively, is or is  not  in  effect  for  the
       specified  time.  A negative value for tm_isdst causes the
       mktime function to attempt to divine whether  summer  time
       is  in effect for the specified time.)  On successful com-
       pletion, the values of the tm_wday and tm_yday  components
       of the structure are set appropriately, and the other com-
       ponents are set to represent the specified calendar  time,
       but  with  their values forced to their normal ranges; the
       final value of tm_mday is not set until tm_mon and tm_year
       are  determined.   Mktime  returns  the specified calendar
       time; If the  calendar  time  cannot  be  represented,  it
       returns -1.

       Difftime  returns  the  difference  between  two  calendar
       times, (time1 - time0), expressed in seconds.

       Declarations of all the functions and externals,  and  the
       ``tm''  structure,  are  in the <time.h> header file.  The
       structure (of  type)  struct  tm  includes  the  following
       fields:

                   int tm_sec;      /* seconds (0 - 61) */
                   int tm_min;      /* minutes (0 - 59) */
                   int tm_hour;     /* hours (0 - 23) */
                   int tm_mday;     /* day of month (1 - 31) */
                   int tm_mon;      /* month of year (0 - 11) */
                   int tm_year;     /* year - 1900 */
                   int tm_wday;     /* day of week (Sunday = 0) */
                   int tm_yday;     /* day of year (0 - 365) */
                   int tm_isdst;    /* is summer time in effect? */
                   char *tm_zone;   /* abbreviation of timezone name */
                   long tm_gmtoff;  /* offset from UTC in seconds */

       The tm_zone and tm_gmtoff fields exist, and are filled in,
       only if arrangements to do so were made when  the  library
       containing these functions was created.  There is no guar-
       antee that these fields will continue  to  exist  in  this
       form in future releases of this code.

       Tm_isdst is non-zero if summer time is in effect.

       Tm_gmtoff  is  the  offset (in seconds) of the time repre-
       sented from UTC, with positive values indicating  east  of
       the Prime Meridian.




                                                                2





CTIME(3)                                                 CTIME(3)



FILES

       /etc/localtime                  local time zone file
       /usr/share/zoneinfo             time    zone   information
       directory
       /usr/share/zoneinfo/posixrules  used with POSIX-style TZ's
       /usr/share/zoneinfo/GMT         for UTC leap seconds

       If /usr/share/zoneinfo/GMT is absent, UTC leap seconds are
       loaded from /usr/share/zoneinfo/posixrules.


SEE ALSO

       getenv(3), strftime(3), tzset(3), time(3), tzfile(5)


STANDARDS

       The ctime(), difftime(), asctime(), localtime(),  gmtime()
       and mktime() functions conform to ANSI X3.159-1989 (``ANSI
       C'').    The   tzset()   function   conforms    to    IEEE
       Std1003.1-1988 (``POSIX'').


NOTES

       The  return values point to static data; the data is over-
       written by each call.  The tm_zone  field  of  a  returned
       struct  tm  points  to a static array of characters, which
       will also be overwritten at the next call (and by calls to
       tzset).

       Avoid  using  out-of-range values with mktime when setting
       up lunch with promptness sticklers in Riyadh.





























                                                                3