time -- Overview

COHERENT includes a number of routines that allow you to set and manipulate
time, as recorded on the system's  clock, into a variety of formats.  These
routines  should be  adequate for  nearly any  task that  involves temporal
calculations  or the  maintenance of  data gathered over  a long  period of
time.

All functions, global  variables, and manifest constants used in connection
with time are defined and described in the header files time.h and timeb.h.
In  brief, time  manipulates two  data elements: the  type time_t,  and the
structure tm.

time_t is  defined in the header file  <time.h>. COHERENT follows the
UNIX standard and initializes time_t to the number of seconds since January
1, 1970, 0h00m00s GMT; this moment, in turn, is rendered as day 2,440,587.5
on the  Julian calendar.  This  allows accurate calculation of  time as far
back as January 1, 4713 B.C.

The  structure tm  is  defined in  the  header file  <time.h>. It  is
defined as follows:

struct tm {
     int tm_sec;    /* current time, seconds */
     int tm_min;    /* current time, minutes */
     int tm_hour;   /* current time, hour */
     int tm_mday;   /* day of the month, 1-31 */
     int tm_mon;    /* month, 1-12 */
     int tm_year;   /* year since 1900 */
     int tm_wday;   /* day of the week, Sunday = 0 */
     int tm_yday;   /* day in the current year */
     int tm_isdst;  /* is daylight-savings time now in effect? */
};

For  an example  of manipulating  this structure  in a  C program,  see the
Lexicon entry for localtime().

Standard Time Functions

The COHERENT system includes the following functions to manipulate time:

asctime()......Convert time structure to ASCII string
clock()........Get processor time
ctime()........Convert system time to an ASCII string
difftime().....Return difference between two times
gmtime().......Convert system time to calendar structure
localtime()....Convert system time to calendar structure
mktime().......Turn broken-down time into calendar time
strftime().....Format locale-specific time
time().........Get the current time
tzset()........Set local time zone

To print out the local time, a program must perform the following tasks:

1. Read the system time with time(). This function returns a time_t.

2. Pass the  time_t returned  by time()  to the function  localtime(). This
   function breaks it down into the tm structure,

3. Pass  localtime()'s  output   to  asctime(),  which  transforms  the  tm
   structure into an ASCII string.

4. Finally, pass the output of asctime() to printf(), to displays it on the
   standard output device.

See the entry for asctime() for  an example C program that goes through the
above steps.

Special Time Functions

COHERENT  includes a  number of  extensions to the  time functions  used by
standard  UNIX  systems.  These  are  designed to  increase  the scope  and
accuracy of time-handling, and to ease calculation of some time elements.

COHERENT  holds information  about your  time  locale in  the environmental
variable  TIMEZONE. This  variable is  described in  detail in  its Lexicon
article.  In brief, it consists of seven fields:

    1. Name of the local standard time zone
    2. Offset from Greenwich Mean Time, in minutes
    3. Name of the local daylight time zone
    4. Date when daylight-savings time begins
    5. Date when daylight-savings time ends
    6. Hour when daylight-savings time begins
    7. Hour when daylight-savings time ends

The  fields are  defined in  such a  way that  any form  of daylight-saving
adjustment can be handled correctly.  For example, the United States shifts
into daylight-savings  time on  the first  Sunday in April;  whereas Brazil
shifts into daylight-savings time on a set day each spring.

The function tzset() parses TIMEZONE into the following external variables:

timezone  Seconds from GMT to give local time
tzname[2][16]Character array of names of standard and daylight times

For  details on  manipulations these  variable, see  the Lexicon  entry for
tzset().  The  library  libmisc.a  contains  the following  functions  that
convert time from Julian to Gregorian form:

time_to_jday()Convert time_t to the Julian date
jday_to_time()Convert Julian date to time_t
tm_to_jday()Convert tm structure to Julian date
jday_to_tm()Convert Julian date to tm structure

COHERENT's time functions  assume that conversion to the Gregorian calendar
occurred October 1582, when it was first adopted in Rome.  However, various
nations adopted the Gregorian  calendar at different times; for example, it
was adopted in the British Empire (including its American colonies) only in
September 1752.   (This, by the  way, is the  date assumed by  the COHERENT
command cal, as  you would see if you typed  the command cal 9 1752.) Users
in northern  and eastern Europe,  and in European-influenced  areas of Asia
(e.g.,  India)  may  wish  to  to  write their  own  functions  to  convert
historical data properly from the Julian to the Gregorian calendar.

Example

For an example of some time functions, see the entry for asctime().

See Also

cal,
libc,
libmisc

Notes

COHERENT also  includes the system call ftime(),  which returns the current
system time.  Because the ANSI Standard eliminates ftime(), users are urged
to replace this system call with calls to time().

UNIX System  V defines time_t  in header file  <sys/types.h>, whereas
COHERENT  defines it  in  time.h. This  should  not affect  the porting  of
programs from UNIX  to COHERENT, but it may affect  the porting of programs
in the other direction.

© 2012 by Stephen A. Ness