Click above to get retro games delivered to your door ever month!

The Time Package

Description

   Zortech C++ contains an ANSI compatible package of time functions for
   obtaining and displaying system times. These functions require the
   inclusion of the time.h header file.

   The relevant contents of this header file is as follows:

   #define CLOCKS_PER_SEC ((clock_t) 100)

   typedef long clock_t;
   #ifndef __TYPES_H

   typedef long time_t;
   #endif

   /* Structure to contain broken-down time */
   struct tm
   {
            int tm_sec,         /* seconds 0..59 */
            tm_min,             /* minutes 0..59 */
            tm_hour,            /* hour of day 0..23 */
            tm_mday,            /* day of month 1..31 */
            tm_mon,             /* month 0..11 */

            tm_year,            /* years since 1900 */
            tm_wday,            /* day of week, 0..6 (Sun..Sat) */
            tm_yday,            /* day of year, 0..365 */
            tm_isdst;           /* >0 if daylight savings time */
                                /* ==0 if not DST               */
                                /* 0< if don't know             */
   };

   clock_t clock(void);
   double difftime(time_t,time_t);
   time_t mktime(struct tm *);
   time_t time(time_t *);
   char * asctime(const struct tm *);
   char * ctime(const time_t *);
   struct tm * gmtime(const time_t *);
   struct tm * localtime(const time_t *);
   size_t strftime(char *,size_t,const char *,const struct tm *);

   #define difftime(t1,t2) ((double)((time_t)(t1) \
   - (time_t)(t2)))


   /* non-ANSI stuff */

   #define TIMEOFFSET 315558000 /* Unix time - DOS time */
   #define CLK_TCK     CLOCKS_PER_SEC

   void sleep(time_t);
   void usleep(unsigned long);
   void msleep(unsigned long);

   The clock function returns an approximation of the processor time used
   by the calling program up to the time the clock function was called.
   clock always returns the time in units of 1/100th of a second, even
   though on the IBM PC the smallest measurable unit is in fact 1/18th of a
   second. If the value returned by clock is divided by the CLOCKS_PER_SEC
   macro it will yield the time in seconds. The clock function is useful for
   elapsed time calculations.

   The xxxtime functions depend on the operation of the function time. This
   gets the operating system time, if available, and converts it into the

   number of seconds elapsed since 00:00:00 GMT on January 1, 1970. The
   result of this function is returned as a data type time_t, which is defined
   as a long either in time.h or types.h. This figure is then used as a basis for
   difftime, ctime, gmtime and localtime.

   The difftime function is different in purpose from the other three
   functions. It simply returns the difference in seconds between two time_t
   values obtained by calls to time.

   The functions gmtime and localtime take a time_t value obtained from a
   call to time, and convert it into a different representation, as a struct
   tm. This contains the time value broken down into seconds, minutes,
   hours, days, weeks and so on. The function gmtime converts the value
   with respect to Greenwich Mean Time whereas localtime carries out any
   required corrections for time zone and daylight saving time where such
   information is available.

   The struct tm values obtained from gmtime and localtime are
   themselves used as the input to a further set of time functions, mktime,
   asctime and strftime. The function mktime is simply the reverse of

   gmtime and localtime in that it takes a struct tm representation of the
   system time, and converts it back to a time_t representation as seconds
   since 00:00:00 GMT on January 1, 1970.

   The function asctime has a different purpose. It takes the struct tm
   value and converts it into a ascii string, which can be printed, displayed or
   manipulated. The string is 26 characters long and consists of 3 characters
   representing the day of the week e.g. MON, followed by a space and then
   three representing the month e.g. MAR, another space and then two digits
   representing the day in the month. After a further space, the next 8
   characters display the time in hours, minutes and seconds with colon
   separators. There is one further space followed by four digits for the year, a
   newline and the null character to mark the end of the string. A typical
   string would be

    "MON MAR 7 12:21:35 1989\n"

   To bring these functions together, a normal course of action to undertake,
   if the system time is required in a displayable format, would be:


   1.  create a variable of type time_t.
   2.  create a pointer to struct tm.
   3.  create a pointer to char.
   4.  call time with the address of this variable.
   5.  call localtime passing it the value from time as argument, and
       assigning the return value to the struct tm pointer.
   6.  call asctime passing it the struct tm pointer and assigning its
       return value to the char pointer.
   7.  print the char pointer.

   The ctime function allows you to combine phases 5 and 6 above, in that it
   takes a time_t value obtained by a call to time, and returns a pointer to a
   printable string directly. It is exactly equivalent to the localtime,
   asctime sequence above.

   It is important to appreciate that both the gmtime/localtime functions
   and the asctime/ctime functions return a pointer to a static data object,
   in the first case a struct tm , and in the second case a null terminated
   string. These data objects are reused each time one of these functions is
   called, and any previous contents are overwritten. Therefore it is the

   programmer s responsibility to ensure, should one of these values need to
   be retained, that a copy is made of the object in question.

   The final three functions defined in time.h, sleep, usleep and msleep,
   are not strictly part of the time package. Refer to their entries for a
   description of these functions.