dts_intro(3dts)
Introduction to DCE Distributed Time Service (DTS)
Description
The DCE Distributed Time Service programming routines can obtain timestamps that are based on Coordinated Universal Time (UTC), translate between different timestamp
formats, and perform calculations on timestamps. Applications can call the DTS routines from server or clerk systems and use the timestamps that DTS supplies to determine event sequencing, duration,
and scheduling.
The DTS routines can perform the following basic functions:
· Retrieve the current (UTC-based) time from DTS.
· Convert binary timestamps expressed in the UTC time structure to or from tm structure components.
· Convert the binary timestamps expressed in the UTC time structure to or from timespec structure components.
· Convert the binary timestamps expressed in the UTC time structure to or from ASCII strings.
· Compare two binary time values.
· Calculate binary time values.
· Obtain time zone information.
DTS can convert between several types of binary time structures that are based on different calendars and time unit measurements. DTS uses UTC-based time structures, and can convert other types of time structures to its own presentation of UTC-based time.
Absolute time is an interval on a time scale; absolute time measurements are derived from system clocks or external time-providers. For DTS, absolute times reference the UTC standard and include the inaccuracy and other information. When you display an absolute time, DTS converts the time to ASCII text, as shown in the following display:
1992-11-21-13:30:25.785-04:00I000.082
Relative time is a discrete time interval that is often added to or subtracted from an absolute time. A Time Differential Factor (TDF) associated with an absolute time is one example of a relative time. Note that a relative time does not use the calendar date fields, because these fields concern absolute time.
DTS uses the Coordinated Universal Time (UTC) international time standard. The zero hour of UTC is based on the zero hour of Greenwich Mean Time (GMT). The documentation consistently refers to the time zone of the Greenwich Meridian as GMT. However, this time zone is also sometimes referred to as UTC.
The Time Differential Factor (TDF) is the difference between UTC and the time in a particular time zone.
The user's environment determines the time zone rule (details are system dependent). For example, on OSF/1 systems, the user selects a time zone by specifying the TZ environment variable. (The reference information for the localtime( ) system call, which is described in the ctime(3) reference page, provides additional information.)
If the user's environment does not specify a time zone rule, the system's rule is used (details of the rule are system dependent). For example, on OSF/1 systems, the rule in /etc/zoneinfo/localtime applies.
The OSF DCE Application Development Guide - Core Components provides additional information about UTC and GMT, TDF and time zones, and relative and absolute times.
Unless otherwise specified, the default input and output parameters are as follows:
· If NULL is specified for a utc input parameter, the current time is used.
· If NULL is specified for any output parameter, no result is returned.
An alphabetical listing of the DTS portable interface routines and a brief description of each one follows:
| utc_abstime( ) | Computes the absolute value of a relative binary timestamp. |
| utc_addtime( ) | Computes the sum of two binary timestamps; the timestamps can be two relative times or a relative time and an absolute time. |
| utc_anytime( ) | Converts a binary timestamp to a tm structure by using the TDF information contained in the timestamp to determine the TDF returned with the tm structure. |
| utc_anyzone( ) | Gets the time zone label and offset from GMT by using the TDF contained in the utc input parameter. |
| utc_ascanytime( ) | Converts a binary timestamp to an ASCII string that represents an arbitrary time zone. |
| utc_ascgmtime( ) | Converts a binary timestamp to an ASCII string that expresses a GMT time. |
| utc_asclocaltime( ) | Converts a binary timestamp to an ASCII string that represents a local time. |
| utc_ascreltime( ) | Converts a relative binary timestamp to an ASCII string that represents the time. |
| utc_binreltime( ) | Converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy. |
| utc_bintime( ) | Converts a binary timestamp to a timespec structure. |
| utc_boundtime( ) | Given two UTC times, one before and one after an event, returns a single UTC time whose inaccuracy includes the event. |
| utc_cmpintervaltime( ) | Compares two binary timestamps or two relative binary timestamps. |
| utc_cmpmidtime( ) | Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies. |
| utc_gettime( ) | Returns the current system time and inaccuracy as a binary timestamp. |
| utc_getusertime( ) | Returns the time and process-specific TDF, rather than the system-specific TDF. |
| utc_gmtime( ) | Converts a binary timestamp to a tm structure that expresses GMT or the equivalent UTC. |
| utc_gmtzone( ) | Gets the time zone label for GMT. |
| utc_localtime( ) | Converts a binary timestamp to a tm structure that expresses local time. |
| utc_localzone( ) | Gets the local time zone label and offset from GMT, given utc. |
| utc_mkanytime( ) | Converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp. |
| utc_mkascreltime( ) | Converts a NULL-terminated character string that represents a relative timestamp to a binary timestamp. |
| utc_mkasctime( ) | Converts a NULL-terminated character string that represents an absolute timestamp to a binary timestamp. |
| utc_mkbinreltime( ) | Converts a timespec structure expressing a relative time to a binary timestamp. |
| utc_mkbintime( ) | Converts a timespec structure to a binary timestamp. |
| utc_mkgmtime( ) | Converts a tm structure that expresses GMT or UTC to a binary timestamp. |
| utc_mklocaltime( ) | Converts a tm structure that expresses local time to a binary timestamp. |
| utc_mkreltime( ) | Converts a tm structure that expresses relative time to a relative binary timestamp. |
| utc_mulftime( ) | Multiplies a relative binary timestamp by a floating-point value. |
| utc_multime( ) | Multiplies a relative binary timestamp by an integer factor. |
| utc_pointtime( ) | Converts a binary timestamp to three binary timestamps that represent the earliest, most likely, and latest time. |
| utc_reltime( ) | Converts a relative binary timestamp to a tm structure. |
| utc_spantime( ) | Given two (possibly unordered) binary timestamps, returns a single UTC time interval whose inaccuracy spans the two input binary timestamps. |
| utc_subtime( ) | Computes the difference between two binary timestamps that express either an absolute time and a relative time, two relative times, or two absolute times. |
Book: OSF DCE Application Development Guide - Core Components