COHERENT manpages
This page displays the COHERENT manpage for time [Overview].
List of available manpages
Index
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.