1 DCE_DTS DCE Distributed Time Service (DTS) synchronizes the clocks in a networked system. It provides the following facilities: + The dtsd daemon + The DTS control program (dtscp) + The DTS local clock setting program (dtsdate) The DTS is implemented in the dtsd process. Both clerks and servers use the same daemon. The behavior of the dtsd daemon is determined by the dtscp command. Invocation of dtsd leaves it in an idle state. In order for it to assume an identity, it must be "created" with the dtscp create command. After the DTS entity is created, it is still in a non-functioning state. To put it into operation, you must invoke dtscp enable, which causes an immediate synchronization to take place. For more information, see the enable reference page in this chapter. To bring down a DTS entity, you must first stop it with dtscp disable and then delete it with dtscp delete. For more information, see the disable and delete reference pages in this chapter. The dtsdate command sets the local clock of a system to be the same as the host remote_host, running a dtsd server. For more information see the dtsdate reference page in this chapter. Books: DCE Administration Guide DCE Administration Reference 2 Application_Routines NAME dts_intro - Introduction to DCE Distributed Time Service (DTS) DESCRIPTION The DCE Distributed Time Service programming routines can obtain time- stamps that are based on Coordinated Universal Time (UTC), translate between different timestamp formats, and perform calculations on time- stamps. 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 sub- tracted from an absolute time. A 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, since these fields concern absolute time. Coordinated Universal Time (UTC) is the international time standard that DTS uses. 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 some- times 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). 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 OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. The OSF DCE Application Development Guide 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. RELATED INFORMATION Books: OSF DCE Application Development Guide 3 List_of_all_routines 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. 3 utc_abstime NAME utc_abstime - Computes the absolute value of a relative binary timestamp SYNOPSIS #include int utc_abstime( utc_t* result, utc_t *utc ); PARAMETERS Input utc Relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Absolute value of the input relative binary timestamp. DESCRIPTION The utc_abstime() routine computes the absolute value of a relative binary timestamp. The input timestamp represents a relative (delta) time. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example scales a relative time, computes its absolute value, and prints the result. utc_t relutc, scaledutc; char timstr[UTC_MAX_STR_LEN]; /* Make sure relative timestamp represents a positive interval... */ utc_abstime(&relutc, /* Out: Abs-value of rel time */ &relutc); /* In: Relative time to scale */ /* Scale it by a factor of 17... */ utc_multime(&scaledutc, /* Out: Scaled relative time */ &relutc, /* In: Relative time to scale */ 17L); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII relative time */ UTC_MAX_STR_LEN, /* In: Length of input string */ &scaledutc); /* In: Relative time to */ /* convert */ printf("%s\n",timstr); /* Scale it by a factor of 17.65... */ utc_mulftime(&scaledutc, /* Out: Scaled relative time */ &relutc, /* In: Relative time to scale */ 17.65); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII relative time */ UTC_MAX_STR_LEN, /* In: Length of input string */ &scaledutc); /* In: Relative time to */ /* convert */ printf("%s\n",timstr); 3 utc_addtime NAME utc_addtime - Computes the sum of two binary timestamps SYNOPSIS #include int utc_addtime( utc_t* result, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Resulting binary timestamp or relative binary timestamp, depending upon the operation performed: + relative time+relative time=relative time + absolute time+relative time=absolute time + relative time+absolute time=absolute time + absolute time+absolute time is undefined. (See the note later in this reference page.) DESCRIPTION The utc_addtime() routine adds two binary timestamps, producing a third binary timestamp whose inaccuracy is the sum of the two input inaccuracies. One or both of the input timestamps typically represents a relative (delta) time. The TDF in the first input timestamp is copied to the output. The timestamps can be two relative times or a relative time and an absolute time. NOTES Although no error is returned, the combination absolute time+absolute time should not be used. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example shows how to compute a timestamp that represents a time at least 5 seconds in the future. utc_t now, future, fivesec; reltimespec_t tfivesec; timespec_t tzero; /* Construct a timestamp that represents 5 seconds... */ tfivesec.tv_sec = 5; tfivesec.tv_nsec = 0; tzero.tv_sec = 0; tzero.tv_nsec = 0; utc_mkbinreltime(&fivesec, /* Out: 5 secs in binary timestamp */ &tfivesec, /* In: 5 secs in timespec */ &tzero); /* In: 0 secs inaccuracy in timespec */ /* Get the maximum possible current time... * (The NULL input parameter is used to specify the current time.) */ utc_pointtime((utc_t *)0, /* Out: Earliest possible current time */ (utc_t *)0, /* Out: Midpoint of current time */ &now, /* Out: Latest possible current time */ (utc_t *)0); /* In: Use current time */ /* Add 5 seconds to get future timestamp... */ utc_addtime(&future, /* Out: Future binary timestamp */ &now, /* In: Latest possible time now */ &fivesec); /* In: 5 secs */ RELATED INFORMATION Functions: utc_subtime 3 utc_anytime NAME utc_anytime - Converts a binary timestamp to a tm structure SYNOPSIS #include int utc_anytime( struct tm *timetm, long *tns, struct tm *inacctm, long *ins, long *tdf, utc_t *utc ); PARAMETERS Input utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output timetm Time component of the binary timestamp expressed in the timestamp's local time. tns Nanoseconds since the Time component of the binary timestamp. inacctm Seconds of the inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of 0 (zero). The field tm_yday contains the inaccuracy in days. If the inaccuracy is unspecified, all tm structure fields return values of -1. ins Nanoseconds of the inaccuracy component of the binary timestamp. tdf TDF component of the binary timestamp in units of seconds east of GMT. DESCRIPTION The utc_anytime() routine 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. The TDF information contained in the timestamp is returned with the time and inaccuracy components; the TDF component determines the offset from GMT and the local time value of the tm structure. Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example converts a timestamp by using the TDF information in the timestamp, and then prints the result. utc_t evnt; struct tm tmevnt; timespec_t tevnt, ievnt; char tznam[80]; /* Assume evnt contains the timestamp to convert... * * Get time as a tm structure, using the time zone information * in the timestamp... */ utc_anytime(&tmevnt, /* Out: tm struct of time of evnt */ (long *)0, /* Out: nanosec of time of evnt */ (struct tm *)0, /* Out: tm struct of inacc of evnt */ (long *)0, /* Out: nanosec of inacc of evnt */ (int *)0, /* Out: tdf of evnt */ &evnt); /* In: binary timestamp of evnt */ /* Get the time and inaccuracy as timespec structures... */ utc_bintime(&tevnt, /* Out: timespec of time of evnt */ &ievnt, /* Out: timespec of inacc of evnt */ (int *)0, /* Out: tdf of evnt */ &evnt); /* In: Binary timestamp of evnt */ /* Construct the time zone name from time zone information in * the timestamp... */ utc_anyzone(tznam, /* Out: Time zone name */ 80, /* In: Size of time zone name */ (long *)0, /* Out: tdf of event */ (long *)0, /* Out: Daylight saving flag */ &evnt); /* In: Binary timestamp of evnt */ /* Print timestamp in the format: * * 1991-03-05-21:27:50.023I0.140 (GMT-5:00) * 1992-04-02-12:37:24.003Iinf (GMT+7:00) */ printf("%d-%02d-%02d-%02d:%02d:%02d.%03d", tmevnt.tm_year+1900, tmevnt.tm_mon+1, tmevnt.tm_mday, tmevnt.tm_hour, tmevnt.tm_min, tmevnt.tm_sec, (tevnt.tv_nsec/1000000)); if ((long)ievnt.tv_sec == -1) printf("Iinf"); else printf("I%d.%03d", ievnt.tv_sec, (ievnt.tv_nsec/1000000)); printf(" (%s)\n", tznam); RELATED INFORMATION Functions: utc_mkanytime utc_anyzone utc_gettime utc_getusertime utc_gmtime utc_localtime 3 utc_anyzone NAME utc_anyzone - Gets the time zone label and offset from GMT SYNOPSIS #include int utc_anyzone( char *tzname, size_t tzlen, long *tdf, int *isdst, const utc_t *utc ); PARAMETERS Input tzlen Length of the tzname buffer. utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output tzname Character string that is long enough to hold the time zone label. tdf Longword with differential in seconds east of GMT. isdst Integer with a value of -1, indicating that no information is supplied as to whether it is standard time or daylight saving time. A value of -1 is always returned. DESCRIPTION The utc_anyzone() routine gets the time zone label and offset from GMT by using the TDF contained in the utc input parameter. The label returned is always of the form GMT+n or GMT-n where n is the tdf expressed in hours:minutes. (The label associated with an arbitrary time zone is not known; only the offset is known.) NOTES All of the output parameters are optional. No value is returned and no error occurs if the pointer is NULL. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or an insufficient buffer. EXAMPLES See the sample program in the utc_anytime reference page. RELATED INFORMATION Functions: utc_anytime utc_gmtzone utc_localzone 3 utc_ascanytime NAME utc_ascanytime - Converts a binary timestamp to an ASCII string that represents an arbitrary time zone SYNOPSIS #include int utc_ascanytime( char *cp, size_t stringlen, utc_t *utc ); PARAMETERS Input stringlen The length of the cp buffer. utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output cp ASCII string that represents the time. DESCRIPTION The utc_ascanytime() routine converts a binary timestamp to an ASCII string that expresses a time. The TDF component in the timestamp determines the local time used in the conversion. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts a time to an ASCII string that expresses the time in the time zone where the timestamp was generated. utc_t evnt; char localTime[UTC_MAX_STR_LEN]; /* * Assuming that evnt contains the timestamp to convert, * convert the time to ASCII in the following format: * * 1991-04-01-12:27:38.37-8:00I2.00 */ utc_ascanytime(localtime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ &evnt); /* In: Time to convert */ RELATED INFORMATION Functions: utc_ascgmtime utc_asclocaltime 3 utc_ascgmtime NAME utc_ascgmtime - Converts a binary timestamp to an ASCII string that expresses a GMT time SYNOPSIS #include int utc_ascgmtime( char *cp, size_t stringlen, utc_t *utc ); PARAMETERS Input stringlen Length of the cp buffer. utc Binary timestamp. Output cp ASCII string that represents the time. DESCRIPTION The utc_ascgmtime() routine converts a binary timestamp to an ASCII string that expresses a time in GMT. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts the current time to GMT format. char gmTime[UTC_MAX_STR_LEN]; /* Convert the current time to ASCII in the following format: * 1991-04-01-12:27:38.37I2.00 */ utc_ascgmtime(gmTime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ (utc_t*) NULL); /* In: Time to convert */ /* Default is current time */ RELATED INFORMATION Functions: utc_ascanytime utc_asclocaltime 3 utc_asclocaltime NAME utc_asclocaltime - Converts a binary timestamp to an ASCII string that represents a local time SYNOPSIS #include int utc_asclocaltime( char *cp, size_t stringlen, utc_t *utc ); PARAMETERS Input stringlen Length of the cp buffer. utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output cp ASCII string that represents the time. DESCRIPTION The utc_asclocaltime() routine converts a binary timestamp to an ASCII string that expresses local time. The user's environment determines the time zone rule (details are system dependent). 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 OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts the current time to local time. char localTime[UTC_MAX_STR_LEN]; /* Convert the current time... */ utc_asclocaltime(localTime, /* Out: Converted time */ UTC_MAX_STR_LEN, /* In: Length of string */ (utc_t*) NULL); /* In: Time to convert */ /* Default is current time */ RELATED INFORMATION Functions: utc_ascanytime utc_ascgmtime 3 utc_ascreltime NAME utc_ascreltime - Converts a relative binary timestamp to an ASCII string that represents the time SYNOPSIS #include int utc_ascreltime( char *cp, const size_t stringlen, utc_t *utc ); PARAMETERS Input utc Relative binary timestamp. stringlen Length of the cp buffer. Output cp ASCII string that represents the time. DESCRIPTION The utc_ascreltime() routine converts a relative binary timestamp to an ASCII string that represents the time. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES See the sample program in the utc_abstime reference page. RELATED INFORMATION Functions: utc_mkascreltime 3 utc_binreltime NAME utc_binreltime - Converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy SYNOPSIS #include int utc_binreltime( reltimespec_t *timesp, timespec_t *inaccsp, utc_t *utc ); PARAMETERS Input utc Relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output timesp Time component of the relative binary timestamp, in the form of seconds and nanoseconds since the base time (1970-01-01:00:00:00.0+00:00I0). inaccsp Inaccuracy component of the relative binary timestamp, in the form of seconds and nanoseconds. DESCRIPTION The utc_binreltime() routine converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy. These timespec structures describe a time interval. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example measures the duration of a process, then prints the resulting relative time and inaccuracy. utc_t before, duration; reltimespec_t tduration; timespec_t iduration; /* Get the time before the start of the operation... */ utc_gettime(&before); /* Out: Before binary timestamp */ /* ...Later... * Subtract, getting the duration as a relative time. * * NOTE: The NULL argument is used to obtain the current time. */ utc_subtime(&duration, /* Out: Duration rel bin timestamp */ (utc_t *)0, /* In: After binary timestamp */ &before); /* In: Before binary timestamp */ /* Convert the relative times to timespec structures... */ utc_binreltime(&tduration, /* Out: Duration time timespec */ &iduration, /* Out: Duration inacc timespec */ &duration); /* In: Duration rel bin timestamp */ /* Print the duration... */ printf("%d.%04d", tduration.tv_sec, (tduration.tv_nsec/10000)); if ((long)iduration.tv_sec == -1) printf("Iinf\n"); else printf( "I%d.%04d\n", iduration.tv_sec, (iduration.tv_nsec/100000) ); RELATED INFORMATION Functions: utc_mkbinreltime 3 utc_bintime NAME utc_bintime - Converts a binary timestamp to a timespec structure SYNOPSIS #include int utc_bintime( timespec_t *timesp, timespec_t *inaccsp, long *tdf, utc_t *utc ); PARAMETERS Input utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output timesp Time component of the binary timestamp, in the form of seconds and nanoseconds since the base time. inaccsp Inaccuracy component of the binary timestamp, in the form of seconds and nanoseconds. tdf TDF component of the binary timestamp in the form of signed number of seconds east of GMT. DESCRIPTION The utc_bintime() routine converts a binary timestamp to a timespec structure. The TDF information contained in the timestamp is returned. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_anytime reference page. RELATED INFORMATION Functions: utc_binreltime utc_mkbintime 3 utc_boundtime NAME utc_boundtime - Given two UTC times, one before and one after an event, returns a single UTC time whose inaccuracy includes the event SYNOPSIS #include int utc_boundtime( utc_t *result, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Before binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 After binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Spanning timestamp. DESCRIPTION Given two UTC times, the utc_boundtime() routine returns a single UTC time whose inaccuracy bounds the two input times. This is useful for timestamping events: the routine gets the utc values before and after the event, then calls utc_boundtime() to build a timestamp that includes the event. NOTES The TDF in the output UTC value is copied from the utc2 input parameter. If one or both input values have unspecified inaccuracies, the returned time value also has an unspecified inaccuracy and is the average of the two input values. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid parameter order. EXAMPLES The following example records the time of an event and constructs a single timestamp, which includes the time of the event. Note that the utc_getusertime() routine is called so the time zone information that is included in the timestamp references the user's environment rather than the system's default time zone. The user's environment determines the time zone rule (details are system dependent). 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 OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. utc_t before, after, evnt; /* Get the time before the event... */ utc_getusertime(&before); /* Out: Before binary timestamp */ /* Get the time after the event... */ utc_getusertime(&after); /* Out: After binary timestamp */ /* Construct a single timestamp that describes the time of the * event... */ utc_boundtime(&evnt, /* Out: Timestamp that bounds event */ &before, /* In: Before binary timestamp */ &after); /* In: After binary timestamp */ RELATED INFORMATION Functions: utc_gettime utc_pointtime utc_spantime 3 utc_cmpintervaltime NAME utc_cmpintervaltime - Compares two binary timestamps or two relative binary timestamps SYNOPSIS #include int utc_cmpintervaltime( enum utc_cmptype *relation, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output relation Receives the result of the comparison of utc1:utc2 where the result is an enumerated type with one of the following values: + utc_equalTo + utc_lessThan + utc_greaterThan + utc_indeterminate DESCRIPTION The utc_cmpintervaltime() routine compares two binary timestamps and returns a flag indicating that the first time is greater than, less than, equal to, or overlapping with the second time. Two times overlap if the intervals (time - inaccuracy, time + inaccuracy) of the two times intersect. The input binary timestamps express two absolute or two relative times. Do not compare relative binary timestamps to absolute binary timestamps. If you do, no meaningful results and no errors are returned. The following routine does a temporal ordering of the time intervals. utc1 is utc_lessThan utc2 iff utc1.time + utc1.inacc < utc2.time - utc2.inacc utc1 is utc_greaterThan utc2 iff utc1.time - utc1.inacc > utc2.time + utc2.inacc utc1 utc_equalTo utc2 iff utc1.time == utc2.time and utc1.inacc == 0 and utc2.inacc == 0 utc1 is utc_indeterminate with respect to utc2 if the intervals overlap. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. EXAMPLES The following example checks to see if the current time is definitely after 13:00 local time. struct tm tmtime, tmzero; enum utc_cmptype relation; utc_t testtime; /* Zero the tm structure for inaccuracy... */ memset(&tmzero, 0, sizeof(tmzero)); /* Get the current time, mapped to a tm structure... * * NOTE: The NULL argument is used to get the current time. */ utc_gmtime(&tmtime, /* Out: Current GMT time in tm struct */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0,/* Out: Current inaccuracy in tm struct */ (long *)0, /* Out: Nanoseconds of inaccuracy */ (utc_t *)0); /* In: Current timestamp */ /* Alter the tm structure to correspond to 13:00 local time */ tmtime.tm_hour = 13; tmtime.tm_min = 0; tmtime.tm_sec = 0; /* Convert to a binary timestamp... */ utc_mkgmtime(&testtime, /* Out: Binary timestamp of 13:00 */ &tmtime, /* In: 1:00 PM in tm struct */ 0, /* In: Nanoseconds of time */ &tmzero, /* In: Zero inaccuracy in tm struct */ 0); /* In: Nanoseconds of inaccuracy */ /* Compare to the current time. Note the use of the NULL argument */ utc_cmpintervaltime(&relation, /* Out: Comparison relation */ (utc_t *)0, /* In: Current timestamp */ &testtime); /* In: 13:00 PM timestamp */ /* If it is not later - wait, print a message, etc. */ if (relation != utc_greaterThan) { /* * Note: It could be earlier than 13:00 local time or it * could be indeterminate. If indeterminate, for some * applications it might be worth waiting. */ } RELATED INFORMATION Functions: utc_cmpmidtime 3 utc_cmpmidtime NAME utc_cmpmidtime - Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies SYNOPSIS #include int utc_cmpmidtime( enum utc_cmptype *relation, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output relation Result of the comparison of utc1:utc2 where the result is an enumerated type with one of the following values: + utc_equalTo + utc_lessThan + utc_greaterThan DESCRIPTION The utc_cmpmidtime() routine compares two binary timestamps and returns a flag indicating that the first timestamp is greater than, less than, or equal to the second timestamp. Inaccuracy information is ignored for this comparison; the input values are therefore equivalent to the midpoints of the time intervals described by the input binary timestamps. The input binary timestamps express two absolute or two relative times. Do not compare relative binary timestamps to absolute binary timestamps. If you do, no meaningful results and no errors are returned. The following routine does a lexical ordering on the time interval midpoints. utc1 is utc_lessThan utc2 iff utc1.time < utc2.time utc1 is utc_greaterThan utc2 iff utc1.time > utc2.time utc1 is utc_equalTo utc2 iff utc1.time == utc2.time RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. EXAMPLES The following example checks if the current time (ignoring inaccuracies) is after 13:00 local time. struct tm tmtime, tmzero; enum utc_cmptype relation; utc_t testtime; /* Zero the tm structure for inaccuracy... */ memset(&tmzero, 0, sizeof(tmzero)); /* Get the current time, mapped to a tm structure... * * NOTE: The NULL argument is used to get the current * time. */ utc_localtime(&tmtime, /* Out: Current local time in tm struct */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0,/* Out: Current inacc in tm struct */ (long *)0, /* Out: Nanoseconds of inaccuracy */ (utc_t *)0); /* In: Current timestamp */ /* Alter the tm structure to correspond to 13:00 local time. */ tmtime.tm_hour = 13; tmtime.tm_min = 0; tmtime.tm_sec = 0; /* Convert to a binary timestamp... */ utc_mklocaltime(&testtime, /* Out: Binary timestamp of 13:00 */ &tmtime, /* In: 13:00 in tm struct */ 0, /* In: Nanoseconds of time */ &tmzero, /* In: Zero inaccuracy in tm struct */ 0); /* In: Nanoseconds of inaccuracy */ /* Compare to the current time. Note the use of the NULL argument */ utc_cmpmidtime(&relation, /* Out: Comparison relation */ (utc_t *)0, /* In: Current timestamp */ &testtime); /* In: 13:00 local time timestamp */ /* If the time is not later - wait, print a message, etc. */ if (relation != utc_greaterThan) { /* It is not later then 13:00 local time. Note that * this depends on the setting of the user's environment. */ } RELATED INFORMATION Functions: utc_cmpintervaltime 3 utc_gettime NAME utc_gettime - Returns the current system time and inaccuracy as a binary timestamp SYNOPSIS #include int utc_gettime( utc_t *utc ); PARAMETERS Input None. Output utc System time as a binary timestamp. DESCRIPTION The utc_gettime() routine returns the current system time and inaccuracy in a binary timestamp. The routine takes the TDF from the operating system's kernel; the TDF is specified in a system- dependent manner. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Generic error that indicates the time service cannot be accessed. EXAMPLES See the sample program in the utc_binreltime reference page. 3 utc_getusertime NAME utc_getusertime - Returns the time and process-specific TDF, rather than the system-specific TDF SYNOPSIS #include int utc_getusertime( utc_t *utc ); PARAMETERS Input None. Output utc System time as a binary timestamp. DESCRIPTION The utc_getusertime() routine returns the system time and inaccuracy in a binary timestamp. The routine takes the TDF from the user's environment, which determines the time zone rule (details are system dependent). If the user environment does not specify a TDF, the system's TDF is used. The system's time zone rule is applied (details of the rule are system dependent). For example, on OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Generic error that indicates the time service cannot be accessed. EXAMPLES See the sample program in the utc_boundtime reference page. RELATED INFORMATION Functions: utc_gettime 3 utc_gmtime NAME utc_gmtime - Converts a binary timestamp to a tm structure that expresses GMT or the equivalent UTC SYNOPSIS #include int utc_gmtime( struct tm *timetm, long *tns, struct tm *inacctm, long *ins, utc_t *utc ); PARAMETERS Input utc Binary timestamp to be converted to tm structure components. Use NULL if you want this routine to use the current time for this parameter. Output timetm Time component of the binary timestamp. tns Nanoseconds since the Time component of the binary timestamp. inacctm Seconds of the inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of 0 (zero). The field tm_yday contains the inaccuracy in days. If the inaccuracy is unspecified, all tm structure fields return values of -1. ins Nanoseconds of the inaccuracy component of the binary timestamp. If the inaccuracy is unspecified, ins returns a value of -1. DESCRIPTION The utc_gmtime() routine converts a binary timestamp to a tm structure that expresses GMT (or the equivalent UTC). Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_cmpintervaltime reference page. RELATED INFORMATION Functions: utc_anytime utc_gmtzone utc_localtime utc_mkgmtime 3 utc_gmtzone NAME utc_gmtzone - Gets the time zone label for GMT SYNOPSIS #include int utc_gmtzone( char *tzname, size_t tzlen, long *tdf, int *isdst, utc_t *utc ); PARAMETERS Input tzlen Length of buffer tzname. utc Binary timestamp. This parameter is ignored. Output tzname Character string long enough to hold the time zone label. tdf Longword with differential in seconds east of GMT. A value of 0 (zero) is always returned. isdst Integer with a value of 0 (zero), indicating that daylight saving time is not in effect. A value of 0 (zero) is always returned. DESCRIPTION The utc_gmtzone() routine gets the time zone label and zero offset from GMT. Outputs are always tdf=0 and tzname=GMT. This routine exists for symmetry with the utc_anyzone() and the utc_localzone() routines. Use NULL if you want this routine to use the current time for this parameter. NOTES All of the output parameters are optional. No value is returned and no error occurs if the tzname pointer is NULL. RETURN VALUES 0 Indicates that the routine executed successfully (always returned). EXAMPLES The following example prints out the current time in both local time and GMT time. utc_t now; struct tm tmlocal, tmgmt; long tzoffset; int tzdaylight; char tzlocal[80], tzgmt[80]; /* Get the current time once, so both conversions use the same * time... */ utc_gettime(&now); /* Convert to local time, using the process TZ environment * variable... */ utc_localtime(&tmlocal, /* Out: Local time tm structure */ (long *)0, /* Out: Nanosec of time */ (struct tm *)0,/* Out: Inaccuracy tm structure */ (long *)0, /* Out: Nanosec of inaccuracy */ (int *)0, /* Out: TDF of local time */ &now); /* In: Current timestamp (ignore) */ /* Get the local time zone name, offset from GMT, and current * daylight savings flag... */ utc_localzone(tzlocal, /* Out: Local time zone name */ 80, /* In: Length of loc time zone name */ &tzoffset, /* Out: Loc time zone offset in secs */ &tzdaylight,/* Out: Local time zone daylight flag */ &now); /* In: Current binary timestamp */ /* Convert to GMT... */ utc_gmtime(&tmgmt, /* Out: GMT tm structure */ (long *)0, /* Out: Nanoseconds of time */ (struct tm *)0, /* Out: Inaccuracy tm structure */ (long *)0, /* Out: Nanoseconds of inaccuracy */ &now); /* In: Current binary timestamp */ /* Get the GMT time zone name... */ utc_gmtzone(tzgmt, /* Out: GMT time zone name */ 80, /* In: Size of GMT time zone name */ (long *)0, /* Out: GMT time zone offset in secs */ (int *)0, /* Out: GMT time zone daylight flag */ &now); /* In: Current binary timestamp */ /* (ignore) */ /* Print out times and time zone information in the following * format: * * 12:00:37 (EDT) = 16:00:37 (GMT) * EDT is -240 minutes ahead of Greenwich Mean Time. * Daylight savings time is in effect. */ printf("%d:%02d:%02d (%s) = %d:%02d:%02d (%s)\n", tmlocal.tm_hour, tmlocal.tm_min, tmlocal.tm_sec, tzlocal, tmgmt.tm_hour, tmgmt.tm_min, tmgmt.tm_sec, tzgmt); printf( "%s is %d minutes ahead of Greenwich Mean Time\n", tzlocal, tzoffset/60 ); if (tzdaylight != 0) printf("Daylight savings time is in effect\n"); RELATED INFORMATION Functions: utc_anyzone utc_gmtime utc_localzone 3 utc_localtime NAME utc_localtime - Converts a binary timestamp to a tm structure that expresses local time SYNOPSIS #include int utc_localtime( struct tm *timetm, long *tns, struct tm *inacctm, long *ins, utc_t *utc ); PARAMETERS Input utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output timetm Time component of the binary timestamp, expressing local time. tns Nanoseconds since the Time component of the binary timestamp. inacctm Seconds of the inaccuracy component of the binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of 0 (zero). The field tm_yday contains the inaccuracy in days. If the inaccuracy is unspecified, all tm structure fields return values of -1. ins Nanoseconds of the inaccuracy component of the binary timestamp. If the inaccuracy is unspecified, ins returns a value of -1. DESCRIPTION The utc_localtime() routine converts a binary timestamp to a tm structure that expresses local time. The user's environment determines the time zone rule (details are system dependent). 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 OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_gmtzone reference page. RELATED INFORMATION Functions: utc_anytime utc_gmtime utc_localzone utc_mklocaltime 3 utc_localzone NAME utc_localzone - Gets the local time zone label and offset from GMT, given utc SYNOPSIS #include int utc_localzone( char *tzname, size_t tzlen, long *tdf, int *isdst, utc_t *utc ); PARAMETERS Input tzlen Length of the tzname buffer. utc Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output tzname Character string long enough to hold the time zone label. tdf Longword with differential in seconds east of GMT. isdst Integer with a value of 0 (zero) if standard time is in effect or a value of 1 if daylight saving time is in effect. DESCRIPTION The utc_localzone() routine gets the local time zone label and offset from GMT, given utc. The user's environment determines the time zone rule (details are system dependent). 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 OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. NOTES All of the output parameters are optional. No value is returned and no error occurs if the pointer is NULL. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or an insufficient buffer. EXAMPLES See the sample program in the utc_gmtzone reference page. RELATED INFORMATION Functions: utc_anyzone utc_gmtzone utc_localtime 3 utc_mkanytime NAME utc_mkanytime - Converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp SYNOPSIS #include int utc_mkanytime( utc_t *utc, struct tm *timetm, long tns, struct tm *inacctm, long ins, long tdf ); PARAMETERS Input timetm A tm structure that expresses the local time; tm_wday and tm_yday are ignored on input; the value of tm_isdt should be -1. tns Nanoseconds since the Time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If a null pointer is passed, or if tm_yday is negative, the inaccuracy is considered to be unspecified; tm_mday, tm_mon, tm_wday, and tm_isdst are ignored on input. ins Nanoseconds of the inaccuracy component. tdf Time Differential Factor to use in conversion. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkanytime() routine converts a tm structure and TDF (expressing the time in an arbitrary time zone) to a binary timestamp. Required inputs include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example converts a string ISO format time in an arbitrary time zone to a binary timestamp. This may be part of an input timestamp routine, although a real implementation will include range checking. utc_t utc; struct tm tmtime, tminacc; float tsec, isec; double tmp; long tnsec, insec; int i, offset, tzhour, tzmin, year, mon; char *string; /* Try to convert the string... */ if(sscanf(string, "%d-%d-%d-%d:%d:%e+%d:%dI%e", &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour, &tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) { /* Try again with a negative TDF... */ if (sscanf(string, "%d-%d-%d-%d:%d:%e-%d:%dI%e", &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour, &tmtime.tm_min, &tsec, &tzhour, &tzmin, &isec) != 9) { /* ERROR */ exit(1); } /* TDF is negative */ tzhour = -tzhour; tzmin = -tzmin; } /* Fill in the fields... */ tmtime.tm_year = year - 1900; tmtime.tm_mon = --mon; tmtime.tm_sec = tsec; tnsec = (modf(tsec, &tmp)*1.0E9); offset = tzhour*3600 + tzmin*60; tminacc.tm_sec = isec; insec = (modf(isec, &tmp)*1.0E9); /* Convert to a binary timestamp... */ utc_mkanytime(&utc, /* Out: Resultant binary timestamp */ &tmtime, /* In: tm struct that represents input */ tnsec, /* In: Nanoseconds from input */ &tminacc,/* In: tm struct that represents inacc */ insec, /* In: Nanoseconds from input */ offset); /* In: TDF from input */ RELATED INFORMATION Functions: utc_anytime utc_anyzone 3 utc_mkascreltime NAME utc_mkascreltime - Converts a NULL-terminated character string that represents a relative timestamp to a binary timestamp SYNOPSIS #include int utc_mkascreltime( utc_t *utc, char *string ); PARAMETERS Input string A NULL-terminated string that expresses a relative timestamp in its ISO format. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkascreltime() routine converts a NULL-terminated string, which represents a relative timestamp, to a binary timestamp. NOTES The ASCII string must be NULL-terminated. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts an ASCII relative time string to its binary equivalent. utc_t utc; char str[UTC_MAX_STR_LEN]; /* Relative time of -333 days, 12 hours, 1 minute, 37.223 * seconds Inaccuracy of 50.22 seconds in the format: * -333-12:01:37.223I50.22 */ (void)strcpy((void *)str, "-333-12:01:37.223I50.22"); utc_mkascreltime(&utc, /* Out: Binary utc */ str); /* In: String */ RELATED INFORMATION Functions: utc_ascreltime 3 utc_mkasctime NAME utc_mkasctime - Converts a NULL-terminated character string that represents an absolute timestamp to a binary timestamp SYNOPSIS #include int utc_mkasctime( utc_t *utc, char *string ); PARAMETERS Input string A NULL-terminated string that expresses an absolute time. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkasctime() routine converts a NULL-terminated string that represents an absolute time to a binary timestamp. NOTES The ASCII string must be NULL-terminated. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time parameter or invalid results. EXAMPLES The following example converts an ASCII time string to its binary equivalent. utc_t utc; char str[UTC_MAX_STR_LEN]; /* July 4, 1776, 12:01:37.223 local time * TDF of -5:00 hours * Inaccuracy of 3600.32 seconds */ (void)strcpy((void *)str, "1776-07-04-12:01:37.223-5:00I3600.32"); utc_mkasctime(&utc, /* Out: Binary utc */ str); /* In: String */ RELATED INFORMATION Functions: utc_ascanytime utc_ascgmtime utc_asclocaltime 3 utc_mkbinreltime NAME utc_mkbinreltime - Converts a timespec structure expressing a relative time to a binary timestamp SYNOPSIS #include int utc_mkbinreltime( utc_t *utc, reltimespec_t *timesp, timespec_t *inaccsp ); PARAMETERS Input timesp A reltimespec structure that expresses a relative time. inaccsp A timespec structure that expresses inaccuracy. If a null pointer is passed, or if tv_sec is set to a value of -1, the inaccuracy is considered to be unspecified. Output utc Resulting relative binary timestamp. DESCRIPTION The utc_mkbinreltime() routine converts a timespec structure that expresses relative time to a binary timestamp. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_addtime reference page. RELATED INFORMATION Functions: utc_binreltime utc_mkbintime 3 utc_mkbintime NAME utc_mkbintime - Converts a timespec structure to a binary timestamp SYNOPSIS #include int utc_mkbintime( utc_t *utc, timespec_t *timesp, timespec_t *inaccsp, long tdf ); PARAMETERS Input timesp A timespec structure that expresses time since 1970-01-01:00:00:00.0+0:00I0. inaccsp A timespec structure that expresses inaccuracy. If a null pointer is passed, or if tv_sec is set to a value of -1, the inaccuracy is considered to be unspecified. tdf TDF component of the binary timestamp. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkbintime() routine converts a timespec structure time to a binary timestamp. The TDF input is used as the TDF of the binary timestamp. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example obtains the current time from time(), converts it to a binary timestamp with an inaccuracy of 5.2 seconds, and specifies GMT. timespec_t ttime, tinacc; utc_t utc; /* Obtain the current time (without the inaccuracy)... */ ttime.tv_sec = time((time_t *)0); ttime.tv_nsec = 0; /* Specify the inaccuracy... */ tinacc.tv_sec = 5; tinacc.tv_nsec = 200000000; /* Convert to a binary timestamp... */ utc_mkbintime(&utc, /* Out: Binary timestamp */ &ttime, /* In: Current time in timespec */ &tinacc, /* In: 5.2 seconds in timespec */ 0); /* In: TDF of GMT */ RELATED INFORMATION Functions: utc_bintime utc_mkbinreltime 3 utc_mkgmtime NAME utc_mkgmtime - Converts a tm structure that expresses GMT or UTC to a binary timestamp SYNOPSIS #include int utc_mkgmtime( utc_t *utc, struct tm *timetm, long tns, struct tm *inacctm, long ins ); PARAMETERS Input timetm A tm structure that expresses GMT. On input, tm_wday and tm_yday are ignored; the value of tm_isdt should be -1. tns Nanoseconds since the Time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If a null pointer is passed, or if tm_yday is negative, the inaccuracy is considered to be unspecified. On input, tm_mday, tm_mon, tm_wday, and tm_isdst are ignored. ins Nanoseconds of the inaccuracy component. Output utc Resulting binary timestamp. DESCRIPTION The utc_mkgmtime() routine converts a tm structure that expresses GMT or UTC to a binary timestamp. Additional inputs include nanoseconds since the last second of Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_cmpintervaltime reference page. RELATED INFORMATION Functions: utc_gmtime 3 utc_mklocaltime NAME utc_mklocaltime - Converts a tm structure that expresses local time to a binary timestamp SYNOPSIS #include int utc_mklocaltime( utc_t *utc, struct tm *timetm, long tns, struct tm *inacctm, long ins ); PARAMETERS Input timetm A tm structure that expresses the local time. On input, tm_wday and tm_yday are ignored; the value of tm_isdst should be -1. tns Nanoseconds since the Time component. inacctm A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If a null pointer is passed, or if tm_yday is negative, the inaccuracy is considered to be unspecified. On input, tm_mday, tm_mon, tm_wday, and tm_isdst are ignored. ins Nanoseconds of the inaccuracy component. Output utc Resulting binary timestamp. DESCRIPTION The utc_mklocaltime() routine converts a tm structure that expresses local time to a binary timestamp. The user's environment determines the time zone rule (details are system dependent). 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 OpenVMS systems, the rule pointed to by the filename in SYS$SYSTEM:SYS$TIMEZONE_SRC.DAT applies. Additional inputs include nanoseconds since the last second of Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_cmpmidtime reference page. RELATED INFORMATION Functions: utc_localtime 3 utc_mkreltime NAME utc_mkreltime - Converts a tm structure that expresses relative time to a relative binary timestamp SYNOPSIS #include int utc_mkreltime( utc_t *utc, struct tm *timetm, long tns, struct tm *inacctm, long ins ); PARAMETERS Input timetm A tm structure that expresses a relative time. On input, tm_wday and tm_yday are ignored; the value of tm_isdst should be -1. tns Nanoseconds since the Time component. inacctm A tm structure that expresses seconds of inaccuracy. If a null pointer is passed, or if tm_yday is negative, the inaccuracy is considered to be unspecified. On input, tm_mday, tm_mon, tm_year, tm_wday, tm_isdst, and tm_zone are ignored. ins Nanoseconds of the inaccuracy component. Output utc Resulting relative binary timestamp. DESCRIPTION The utc_mkreltime() routine converts a tm structure that expresses relative time to a relative binary timestamp. Additional inputs include nanoseconds since the last second of Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example converts the relative time: 125-03:12:30.1I120.25 to a relative binary timestamp. utc_t utc; struct tm tmtime,tminacc; long tnsec,insec; /* Fill in the fields */ memset((void *)&tmtime,0,sizeof(tmtime)); tmtime.tm_mday = 125; tmtime.tm_hour = 3; tmtime.tm_min = 12; tmtime.tm_sec = 30; tnsec = 100000000; /* .1 * 1.0E9 */ memset((void *)&tminacc,0,sizeof(tminacc)); tminacc.tm_sec = 120; tnsec = 250000000; /* .25 * 1.0E9 */ /* Convert to a relative binary timestamp... */ utc_mkreltime(&utc, /* Out: Resultant relative binary timestamp */ &tmtime, /* In: tm struct that represents input */ tnsec, /* In: Nanoseconds from input */ &tminacc, /* In: tm struct that represents inacc */ insec); /* In: Nanoseconds from input */ 3 utc_mulftime NAME utc_mulftime - Multiplies a relative binary timestamp by a floating-point value. SYNOPSIS #include int utc_mulftime( utc_t *result, utc_t *utc1, double factor ); PARAMETERS Input utc1 Relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. factor Real scale factor (double-precision, floating-point value). Output result Resulting relative binary timestamp. DESCRIPTION The utc_mulftime() routine multiplies a relative binary timestamp by a floating-point value. Either or both may be negative; the resulting relative binary timestamp has the appropriate sign. The unsigned inaccuracy in the relative binary timestamp is also multiplied by the absolute value of the floating-point value. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example scales a relative time by a floating-point factor and prints the result. utc_t relutc, scaledutc; struct tm scaledreltm; char timstr[UTC_MAX_STR_LEN]; /* Assume relutc contains the time to scale. */ utc_mulftime(&scaledutc, /* Out: Scaled rel time */ &relutc, /* In: Rel time to scale */ 17.65); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII rel time */ UTC_MAX_STR_LEN, /* In: Input buffer length */ &scaledutc); /* In: Rel time to convert */ printf("%s\n",timstr); /* Convert it to a tm structure and print it. */ utc_reltime(&scaledreltm, /* Out: Scaled rel tm */ (long *)0, /* Out: Scaled rel nano-sec */ (struct tm *)0, /* Out: Scaled rel inacc tm */ (long *)0, /* Out: Scd rel inacc nanos */ &scaledutc); /* In: Rel time to convert */ printf( "Approximately %d days, %d hours and %d minutes\n", scaledreltm.tm_yday, scaledreltm.tm_hour, scaledreltm.tm_min ); RELATED INFORMATION Functions: utc_multime 3 utc_multime NAME utc_multime - Multiplies a relative binary timestamp by an integer factor SYNOPSIS #include int utc_multime( utc_t *result, utc_t *utc1, long factor ); PARAMETERS Input utc1 Relative binary timestamp. factor Integer scale factor. Output result Resulting relative binary timestamp. DESCRIPTION The utc_multime() routine multiplies a relative binary timestamp by an integer. Either or both may be negative; the resulting binary timestamp has the appropriate sign. The unsigned inaccuracy in the binary timestamp is also multiplied by the absolute value of the integer. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES The following example scales a relative time by an integral value and prints the result. utc_t relutc, scaledutc; char timstr[UTC_MAX_STR_LEN]; /* Assume relutc contains the time to scale. Scale it by a * factor of 17 ... */ utc_multime(&scaledutc, /* Out: Scaled rel time */ &relutc, /* In: Rel time to scale */ 17L); /* In: Scale factor */ utc_ascreltime(timstr, /* Out: ASCII rel time */ UTC_MAX_STR_LEN, /* In: Input buffer length */ &scakedutc); /* In: Rel time to convert */ printf("Scaled result is %s0, timstr); RELATED INFORMATION Functions: utc_mulftime 3 utc_pointtime NAME utc_pointtime - Converts a binary timestamp to three binary timestamps that represent the earliest, most likely, and latest time SYNOPSIS #include int utc_pointtime( utc_t *utclp, utc_t *utcmp, utc_t *utchp, utc_t *utc ); PARAMETERS Input utc Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output utclp Lowest (earliest) possible absolute time or shortest possible relative time that the input timestamp can represent. utcmp Midpoint of the input timestamp. utchp Highest (latest) possible absolute time or longest possible relative time that the input timestamp can represent. DESCRIPTION The utc_pointtime() routine converts a binary timestamp to three binary timestamps that represent the earliest, latest, and most likely (midpoint) times. If the input is a relative binary time, the outputs represent relative binary times. NOTES All outputs have zero inaccuracy. An error is returned if the input binary timestamp has an unspecified inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. EXAMPLES See the sample program in the utc_addtime reference page. RELATED INFORMATION Functions: utc_boundtime utc_spantime 3 utc_reltime NAME utc_reltime - Converts a relative binary timestamp to a tm structure SYNOPSIS #include int utc_reltime( struct tm *timetm, long *tns, struct tm *inacctm, long *ins, utc_t *utc ); PARAMETERS Input utc Relative binary timestamp. Output timetm Relative time component of the relative binary timestamp. The field tm_mday returns a value of -1 and the fields tm_year and tm_mon return values of 0 (zero). The field tm_yday contains the number of days of relative time. tns Nanoseconds since the Time component of the relative binary timestamp. inacctm Seconds of the inaccuracy component of the relative binary timestamp. If the inaccuracy is finite, then tm_mday returns a value of -1 and tm_mon and tm_year return values of 0 (zero). The field tm_yday contains the inaccuracy in days. If the inaccuracy is unspecified, all tm structure fields return values of -1. ins Nanoseconds of the inaccuracy component of the relative binary timestamp. DESCRIPTION The utc_reltime() routine converts a relative binary timestamp to a tm structure. Additional returns include nanoseconds since Time and nanoseconds of inaccuracy. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_mulftime reference page. RELATED INFORMATION Functions: utc_mkreltime 3 utc_spantime NAME utc_spantime - Given two (possibly unordered) binary timestamps, returns a single UTC time interval whose inaccuracy spans the two input binary timestamps SYNOPSIS #include int utc_spantime( utc_t *result, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Spanning timestamp. DESCRIPTION Given two binary timestamps, the utc_spantime() routine returns a single UTC time interval whose inaccuracy spans the two input timestamps (that is, the interval resulting from the earliest possible time of either timestamp to the latest possible time of either timestamp). NOTES The tdf parameter in the output UTC value is copied from the utc2 input. If either input binary timestamp has an unspecified inaccuracy, an error is returned. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument. EXAMPLES The following example computes the earliest and latest times for an array of 10 timestamps. utc_t time_array[10], testtime, earliest, latest; int i; /* Set the running timestamp to the first entry... */ testtime = time_array[0]; for (i=1; i<10; i++) { /* Compute the minimum and the maximum against the next * element... */ utc_spantime(&testtime, /* Out: Resultant interval */ &testtime, /* In: Largest previous interval */ &time_array[i]); /* In: Element under test */ } /* Compute the earliest and latest possible times */ utc_pointtime(&earliest, /* Out: Earliest poss time in array */ (utc_t *)0, /* Out: Midpoint */ &latest, /* Out: Latest poss time in array */ &testtime); /* In: Spanning interval */ RELATED INFORMATION Functions: utc_boundtime utc_gettime utc_pointtime 3 utc_subtime NAME utc_subtime - Computes the difference between two binary timestamps SYNOPSIS #include int utc_subtime( utc_t *result, utc_t *utc1, utc_t *utc2 ); PARAMETERS Input utc1 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. utc2 Binary timestamp or relative binary timestamp. Use NULL if you want this routine to use the current time for this parameter. Output result Resulting binary timestamp or relative binary timestamp, depending upon the operation performed: + absolute time-absolute time=relative time + relative time-relative time=relative time + absolute time-relative time=absolute time + relative time-absolute time is undefined. (See the note later in this reference page.) DESCRIPTION The utc_subtime() routine subtracts one binary timestamp from another. The two binary timestamps express either an absolute time and a relative time, two relative times, or two absolute times. The resulting timestamp is utc1 minus utc2. The inaccuracies of the two input timestamps are combined and included in the output timestamp. The TDF in the first timestamp is copied to the output. NOTES Although no error is returned, the combination relative time- absolute time should not be used. RETURN VALUES 0 Indicates that the routine executed successfully. -1 Indicates an invalid time argument or invalid results. EXAMPLES See the sample program in the utc_binreltime reference page. RELATED INFORMATION Functions: utc_addtime 2 dtscp_commands NAME Intro - Introduction to the DCE DTS control program commands DESCRIPTION The DCE Distributed Time Service control program (dtscp) allows you to synchronize, adjust, and maintain the system clocks in a distributed network. The DTS control program commands are listed below: + The advertise command, which configures the DTS server as a global server + The change command, which modifies the epoch and sets the local time to a new time + The create command, which establishes a DTS entity (a clerk or server) + The delete command, which causes DTS to exit on the local node + The disable command, which suspends a DTS entity + The enable command, which starts a DTS entity + The exit command, which ends the dtscp management session and returns you to the system prompt + The help command which invokes the dtscp help service. + The quit command, which ends the dtscp management session and returns you to the system prompt + The set command, which modifies characteristics of a DTS entity + The show command, which displays characteristics of a DTS entity + The synchronize command, which synchronizes the system clock with the time obtained from DTS servers in the network + The unadvertise command, which removes the global server entry + The update command, which gradually adjusts the system clock to a new time RELATED INFORMATION Command: dtscp Books: DCE Administration Guide DCE Administration Reference 3 advertise NAME advertise - Configures the system as a global server by adding the server's entry to the cell profile SYNOPSIS dtscp advertise DESCRIPTION The advertise command causes DTS to forward the name and attributes of the server to CDS by binding the server's protocol tower to the CDS object and adding an entry for the server in the cell profile. Once the server's entry is in the cell profile, it is configured as a global server, and servers outside of the LAN can access it. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES dtscp> advertise RELATED INFORMATION Commands: unadvertise 3 change NAME change - Alters the epoch number and time on the local node SYNOPSIS dtscp change epoch integer [time absolute-time] OPTIONS epoch integer Specifies the new epoch number (0-255). This argument is required. time absolute-time Specifies a clock setting for the new epoch. If you do not supply this argument and a value, the server uses the current clock time with an unspecified inaccuracy and initiates a synchronization. This argument is optional. DESCRIPTION The change command sets the time and changes the epoch of the DTS server on which it is entered. Use this command to isolate a server from the rest of the servers in the network before changing the time. Permissions Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES This command is valid only for servers. The new epoch number you specify must be different from the current epoch number. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES 1. The following example shows how to change the epoch number: dtscp> change epoch 1 2. The following example shows how to change the epoch number and time: dtscp> change epoch 1 time 1990-11-30-10:58:00.000-05:00I0.000 3 create NAME create - Creates the DCE DTS entity on the specified node SYNOPSIS dtscp create type OPTIONS type Specifies the type of DCE DTS entity to be created on the specified node. Specify one of the following for : clerk The DCE DTS entity is created as a clerk. (The default setting is clerk.) server The DCE Distributed Time Service entity is created as a server. DESCRIPTION The create command creates a time server or time clerk entity on the system where the command is entered. After the DTS entity is created, it is still in a non-functioning state. To put it into operation, you must invoke dtscp enable, which causes an immediate synchronization to take place. For more information, see the enable reference page in this chapter. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE dtscp> create type server 3 delete NAME delete - Deletes the DCE DTS entity SYNOPSIS dtscp delete DESCRIPTION The delete command deletes the DCE DTS entity from the system where the command is entered. When delete is executed, the DTS daemon process completes execution. To restart the DTS daemon, use the SYS$MANAGER:DCE$SETUP.COM command procedure. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The DCE DTS entity cannot be deleted until you enter the disable command, which causes the status attribute state to be set to off. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLE dtscp> delete RELATED INFORMATION Commands: disable 3 disable NAME disable - Stops the DCE DTS entity on the local node SYNOPSIS dtscp disable DESCRIPTION The disable command turns off the DCE DTS entity on the system where the command is entered. When the command is executed, the status attribute state is set to off. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The DCE DTS entity cannot be disabled until it is enabled with the enable command. You must enter the disable command before you can delete the entity. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES dtscp> disable RELATED INFORMATION Commands: enable delete create 3 enable NAME enable - Starts the DTS entity on the local node. SYNOPSIS dtscp enable [set clock ] ARGUMENTS set clock Specifies whether the clock is abruptly set or gradually adjusted to the computed time. This argument is optional. Valid values for are: false The clock is gradually adjusted. This is the default condition. true The clock is abruptly set. DESCRIPTION After the DTS entity is created with the dtscp create command, it is still in a non-functioning state. To put it into operation, you must invoke dtscp enable, which causes an immediate synchronization to take place. When the command is executed, the status attribute state is set to on. In addition, you may use the enable command to activate a DTS entity that has previously been deactivated with the disable command. See the disable reference page in this chapter for more information. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The DTS entity cannot be enabled until it is created with the create command; the DTS entity must be in the off state. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES 1. The following example shows how to enable the entity and adjust the clock gradually to the computed time following the first synchronization: dtscp> enable 2. The following example shows how to enable the entity and abruptly set the clock to the computed time following the first synchronization: dtscp> enable set clock true RELATED INFORMATION Commands: create disable 3 exit NAME exit - Causes dtscp to complete execution. SYNOPSIS dtscp exit DESCRIPTION The exit command causes the DTS control program (dtscp) to complete execution and returns operation to the parent process. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command shows how to leave dtscp and return to the parent process: dtscp> exit RELATED INFORMATION Commands: quit 3 help NAME help - Displays help information about dtscp commands. SYNOPSIS dtscp help [help-topic] ARGUMENTS help-topic Specifies the help topic for which help information is to be displayed. The following are valid help topics: + advertise + change + create + delete + disable + enable + set + show + synchronize + unadvertise + update DESCRIPTION The help command displays information about dtscp commands. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command shows how to get help about the help subtopic unadvertise. dtscp> help unadvertise 3 quit NAME quit - Causes dtscp to complete execution SYNOPSIS dtscp quit DESCRIPTION The quit command causes dtscp to complete execution and returns operation to the parent process. NOTE This command may be replaced in future releases by the dcecp command, and may no longer be supported at that time. EXAMPLES The following command shows how to leave dtscp and return to the parent process: dtscp> quit RELATED INFORMATION Command: exit 3 set NAME set - Modifies characteristics for the DTS entity. SYNOPSIS dtscp set characteristic ARGUMENTS characteristic The name and value of one or more characteristics to be modified. Valid values for characteristic are described in the following list. These values are described in more detail in the description section. + check interval [relative-time] + courier role [role] + error tolerance [relative-time] + global set timeout [relative-time] + local set timeout [relative-time] + maximum inaccuracy [relative-time] + query attempts [integer] + server entry name [name] + server group name [name] + server principal name [name] + servers required [integer] + synchronization hold down [relative-time] DESCRIPTION The set command modifies the charactistics you specify for the DTS entity. The modifiable characteristics and their values are described in the following list. check interval [relative-time] Specifies the amount of time between checks for faulty servers. Applicable only for servers that have external time providers. Default: 0-01:30:00.000 Value: 0-00:00:30.000 - 10675199-02:48:05.000 courier role [role] Specifies a server's interaction with the set of global servers. Default: backup courier The following values are valid: backup courier The local server becomes a courier if none are available on the LAN. courier The local server synchronizes with the global set of servers. noncourier The local server does not synchronize with the global set of servers. error tolerance [relative-time] Specifies the maximum separation allowed between the local clock and the computed time before synchronizations become abrupt rather than gradual (monotonic). Default: 0-00:10:00.000 Value: 0-00:00:00.500 - 10675199-02:48:05.000 global set timeout [relative-time] Specifies the amount of time the node waits for a response to a global synchronization request before sending another request or declaring a global server to be unavailable. The number of attempts made to reach the server is controlled by the query attemps characteristic. Default: 0-00:00:15.000 Value: 0-00:00:00.000 - 0-00:10:00.000 local set timeout [relative-time] Specifies the amount of time the node waits for a response to a local synchronization request before sending another request or declaring a server to be unavailable. The number of attempts made to reach the server is controlled by the query attemps characteristic. Note that the local set timeout value controls only the initial contact with a time provider. During this initial contact, the time provider itself determines the timeout value for actually reporting back times. This allows a time provider attached to a slow source like a modem to request that dtsd wait for a longer interval. Default: 0-00:00:05.000 Value: 0-00:00:00.000 - 0-00:01:00.000 maximum inaccuracy [relative-time] Specifies the inaccuracy limit for the node. When the node exceeds the maximum inaccuracy setting, it attempts to synchronize. Default: 0-00:00:00.100 Value: 0-00:00:00.000 - 10675199-02:48:05.000 query attempts [integer] Specifies the number of attempts that a node makes to contact a server before the node considers the server unavailable. Default: 3 Value: 1-10 server entry name [name] Specifies a server's CDS entry name; hostname represents the name of the system or node that is the server's client. The default setting is the recommended value. Default: /.:/hosts/hostname/dts-entity server group name [name] Specifies the name of the security group that DTS uses for authentication checks. DTS clerks and servers do not accept time values from DTS servers that are not included in this group. server principal name [name] Specifies a server's principal name for authentication purposes; hostname represents the name of the system or node that is the server's client. The default setting is the recommended value. Default: /.:/hosts/hostname/self servers required [integer] Specifies the minimum number of servers required for a synchronization. Settings of 1 or 2 may cause unreliable computed times. Default: 1 (clerks) 3 (servers) Value: 1-10 synchronization hold down [relative-time] Specifies the interval a node must wait to synchronize. Also specifies synchronization frequency when a node reaches the value specified by the maximum inaccuracy characteristic. Clerks: Default: 0-00:10:00.000 Value: 0-00:00:30.000 - 01-00:00:00.000 Servers: Default: 0-00:02:00.000 Value: 0-00:00:30.000 - 01-00:00:00.000 Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. The following two commands are obsolete. Use the replacements shown. set lan timeout This command is the same as set local set timeout. set wan timeout This command is the same as set global set timeout. EXAMPLES 1. The following example command sets the check interval characteristic to 30 seconds: dtscp> set check interval 00-00:00:30.000 2. The following example shows how to set the number of servers required before the entity can synchronize: dtscp> set servers required 4 3. The following example shows how to set the courier role for a server: dtscp> set courier role backup courier 4. The following example command sets the error tolerance characteristic to seven minutes: dtscp> set error tolerance 0-00:07:00.000 5. The following example command the global set timeout characteristic to 45 seconds: dtscp> set global set timeout 0-00:00:45.000 6. The following example command the local set timeout characteristic to five seconds: dtscp> set local set timeout 0-00:00:05.000 7. The following example command sets the maximum inaccuracy characteristic to three milliseconds: dtscp> set maximum inaccuracy 0-00:00:00.300 8. The following example command sets the server entry name characteristic to /.:/hosts/orion/dts-entity: dtscp> set server entry name /.:/hosts/orion/dts-entity 9. The following example command sets the server principal name characteristic to /.:/hosts/vega/dts-entity: dtscp> set server principal name /.:/hosts/vega/dts-entity 10. The following example command sets the synchronization hold down characteristic to 15 minutes: dtscp> set synchronization hold down 0-00:15:00.000 RELATED INFORMATION Commands: show 3 show NAME show - Displays current information about the DTS entity SYNOPSIS dtscp show attribute-group | attribute-name ARGUMENTS attribute-group The name of an attribute group or individual attribute to be displayed. The following values are valid: + all + all characteristics + all counters + all status + global servers + local servers attribute-name The name of a specific attribute from the characteristics, counters, or status group. The attribute specifiers global servers and local servers do not contain any other attributes. DESCRIPTION The show command displays the names and values of the specified attributes or attribute groups. For attribute groups, if you do not supply a group name with the all argument, all characteristics and their values are displayed. The following sections list names of individual attributes, categorized by group. Note that the attributes displayed by the show command might be different, depending upon whether you have requested information about a server or a clerk. Characteristics Characteristic arguments can contain a maximum of 80 characters and are recalculated to a normalized date format. For example: Input value: 0-0025:10:99.99999999 Result: 1-01:11:39.990 acting courier role Specifies whether a backup courier is currently functioning as a courier. If the role is noncourier, the node is not attempting to synchronize with global servers. This characteristic is shown only for servers. Default: noncourier Value: courier or noncourier automatic tdf change Specifies whether automatic changes to the time differential factor are enabled or disabled; the value is determined by the operating system. Default: true Value: true/false check interval Specifies the amount of time between checks for faulty servers. Applicable only to servers that have external time providers. This characteristic is shown only for servers. Default: 0-01:30:00.00 Value: 0-00:00:30.000 - 10675199-02:48:05.478 clock adjustment rate Specifies the rate at which the DTS server or clerk entity adjusts the node's clock during a synchronization. clock resolution Specifies the amount of time between system clock ticks. The value is determined by the operating system. courier role Specifies a server's interaction with the set of global servers. This characteristic is shown only for servers. backup courier The local server becomes a courier if none are available on the LAN. courier The local server synchronizes with the global set of servers. noncourier The local server does not synchronize with the global set of servers. Default: noncourier DTS version Specifies the DTS software version installed on the node. epoch number Specifies the server's epoch number. The change command modifies this characteristic. This characteristic is shown only for servers. Default: 0 Value: 0-255 error tolerance Specifies the maximum separation allowed between the local clock and the computed time before synchronizations become abrupt rather than gradual (monotonic). Default: 0-00:10:00.000 Value: 0-00:00:00.500 - 10675199-02:48:05.478 global set timeout Specifies the amount of time the node waits for a response to a WAN synchronization request before sending another request or declaring a global server to be unavailable. The number of attempts made to reach the server is controlled by the query attemps characteristic. Default: 0-00:00:15.000 Value: 0-00:00:00.000 - 0-00:10:00.000 local set timeout Specifies the amount of time the node waits for a response to a synchronization request before sending another request or declaring a server to be unavailable. The number of attempts made to reach the server is controlled by the query attemps characteristic. Default: 0-00:00:05.000 Value: 0-00:00:00.000 - 0-00:10:00.000 local time differential factor Specifies the Time Differential Factor (TDF), which is the amount of time the server varies from Greenwich mean time (GMT) or Coordinated Universal Time (UTC). Default: 0-00:00:00.000 Value: -13-00:00:00 - 13-00:00:00 maximum clock drift rate Specifies the worst-case drift rate of the node's clock, in nanoseconds per second, as determined by the manufacturer's specifications. maximum inaccuracy Specifies the inaccuracy limit for the node. When the node exceeds the maximum inaccuracy setting, it attempts to synchronize. Default: 0-00:00:00.100 Value: 0-00:00:00.0 - 10675199-02:48:05.478 next tdf change Specifies the future time at which the time differential factor is automatically changed. The value is determined by the operating system. query attempts Specifies the number of attempts that a node makes to contact a server before the node considers the server unavailable. Default: 3 Value: 1-10 server entry name Specifies a server's ACL entry name; represents the name of the system or node that is the server's client. The default setting is the recommended value. This characteristic is shown only for servers. Default: /.:/hosts//dts-entity server group name Specifies the security group name for the time servers within the cell. Default: /.:/subsys/dce/dts-servers server principal name Specifies a server's principal name for authentication purposes; represents the name of the system or node that is the server's client. The default setting is the recommended value. This characteristic is shown only for servers. Default: /.:/hosts//self servers required Specifies the minimum number of servers required for a synchronization. Settings of 1 or 2 may cause unreliable computed times. Default: 3 Value: 1-10 synchronization hold down Specifies the interval a node must wait to synchronize. Also specifies synchronization frequency when a node reaches the value specified by the maximum inaccuracy characteristic. Clerks: Default: 0-00:10:00.0 Value: 0-00:00:30.0 - 01 00:00:00.00 Servers: Default: 0-00:02.00.0 Value: 0-00:00:30.0 - 01 00:00:00.00 time provider present Specifies whether or not the entity used an external time provider at the last successful synchronization. This attribute applies to servers only. time representation version Specifies the timestamp format used by the node. type Specifies whether the node is a DTS server or clerk. The create command modifies this characteristic. Counters clock settings Specifies the number of times the node clock has been set nonmonotonically (abruptly). creation time Specifies the time at which the DTS entity was created and the counters were initialized. different epochs detected Specifies the number of times the node received time response messages from servers or clerks that had epoch numbers different from its own. This counter is shown only for servers. disable directives completed Specifies the number of times the DTS has been disabled. enable directives completed Specifies the number of times the DTS has been enabled. epoch changes completed Specifies the number of times the server's epoch has changed. insufficient resources detected Specifies the number of times the node has been unable to allocate virtual memory. local servers not in group Specifies the number of times that a local server was contacted, but it was not in the dts security group. local times not intersecting Specifies the number of times the node's time interval failed to intersect with the computed interval of the servers. no global servers detected Specifies the number of times the courier server could not contact any global servers. This counter is shown only for servers. protocol mismatches detected Specifies the number of times the local node failed to process a received message containing an incompatible protocol version. servers not in group Specifies the number of times that a non-local server was contacted, but it was not in the dts security group. This counter is shown only for servers. servers not responding Specifies the number of times the courier server could not contact a specific global server. This counter is shown only for servers. servers times not intersecting Specifies the number of times a server has detected faulty servers (other than itself). This counter is shown only for servers. synchronizations completed Specifies the number of times the node successfully synchronized. system errors detected Specifies the number of times a DTS operation detected a system error. time provider failures detected Specifies the number of times the external time provider signaled a failure or the node was unable to access the time provider. time provider timeouts detected Specifies the number of times a dtsd server process initiated contact with a time provider and did not receive the initial response within the interval specified by local set timeout (the default interval is 5 seconds). This counter is shown only for servers. time representation version mismatches detected Specifies the number of times the local node failed to process a received message containing an incompatible timestamp format. too few servers detected Specifies the number of times a node failed to synchronize because it could not contact the required minimum number of servers. updates initiated Specifies the number of times a server has attempted to update its clock. This counter is shown only for servers. Status current time Specifies the current time on the node. global servers Specifies the set of global servers known by the node. last synchronization Specifies the computed time at the last attempted synchronization. local servers Specifies the set of local servers known by the node. state Specifies the state of the DTS entity. off The DTS entity is disabled. on The DTS entity is enabled. synchronizing The DTS entity is synchronizing. updating The DTS entity is updating the time. uid Specifies the entity's unique identifier, which is generated when the entity is created. This attribute is shown only for servers. Privilege Required You must have read permission on the ACL associated with the DTS entity in order to execute the command. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES 1. The following command shows how to display the current time: dtscp> show current time Current Time = 1990-11-30-12:11:41.718-05:00I0.359 EST 2. The following command shows how to display all of the entity's characteristic attribute settings: dtscp> show all Check Interval = +0-01:30:00.000I----- Epoch Number = 0 Error Tolerance = +0-00:10:00.000I----- Local Time Differential Factor = -0-04:00:00.000I----- Maximum Inaccuracy = +0-00:00:00.100I----- Servers Required = 3 Query Attempts = 3 Local Set Timeout = +0-00:00:05.000I----- Global Set Timeout = +0-00:00:15.000I----- Synchronization Hold Down = +0-00:02:00.000I----- Type = Server Courier Role = NonCourier Acting Courier Role = NonCourier Clock Adjustment Rate = 40000000 nsec/sec Maximum Clock Drift Rate = 1000000 nsec/sec Clock Resolution = 10000000 nsec DTS Version = V1.0.1 Time Representation Version = V1.0.0 Time Provider Present = FALSE Automatic TDF Change = FALSE Next TDF Change = 1993-10-31-06:00:00.000+00:00I0.000 Server Principal Name = hosts/system1/self Server Entry Name = hosts/system1/dts-entity Server Group Name = subsys/dce/dts-servers 3. The following command displays the current values of all characteristic attributes: dtscp> show all characteristics This command produces the same output as does the show all command. 4. The following command shows how to display all of the local servers known to the entity: dtscp> show local servers Known Servers ============================================================ Local /.../sisyphus.osf.org/hosts/system2/self Last Time Polled = 1993-10-15-21:01:46.124+00:00I0.809 Last Observed Time = 1993-10-15-21:03:09.041+00:00I----- Last Observed Skew = +0-00:01:22.917I----- Used in Last Synchronization = TRUE Transport Type = RPC Local /.../sisyphus.osf.org/hosts/system3/self Last Time Polled = 1993-10-15-21:01:46.124+00:00I0.809 Last Observed Time = 1993-10-15-21:01:46.143+00:00I0.817 Last Observed Skew = +0-00:00:00.019I1.625 Used in Last Synchronization = TRUE Transport Type = RPC 5. The following command displays the current values of all counter attributes: dtscp> show all counters Creation Time = 1993-10-14-16:23:57.801+00:00I0.767 Local Times Not Intersecting = 0 Server Times Not Intersecting = 0 Different Epochs Detected = 0 Too Few Servers Detected = 0 Time Provider Timeouts Detected = 1 Protocol Mismatches Detected = 0 Time Representation Mismatches Detected = 0 No Global Servers Detected = 0 Servers Not Responding = 0 Clock Settings = 0 Epoch Changes Completed = 0 System Errors Detected = 0 Synchronizations Completed = 865 Updates Initiated = 0 Enable Directives Completed = 1 Disable Directives Completed = 0 Insufficient Resources Detected = 0 Time Provider Failures Detected = 0 Local server not in group = 0 Servers not in group = 0 6. The following command displays the current values of all status attributes: dtscp> show all status UID = 00004e34-5e1c-2c87-8500-08005a0d4582 Last Synchronization = 1993-10-15-21:05:43.023+00:00I----- State = On 7. The following command displays the current value of the courier role attribute: dtscp> show courier role Courier Role = NonCourier 8. The following command displays the server entry name for this server: dtscp> show server entry name Server Entry Name = hosts/system1/dts-entity 9. The following command displays the current state of the Time Service entity: dtscp> show state State = On 10. The following command displays the current value of the check interval attribute: dtscp> show check interval Check Interval = +0-01:30:00.000I----- 11. The following command displays the current value of the servers times not intersecting counter: dtscp> show servers times not intersecting Server Times Not Intersecting = 0 RELATED INFORMATION Commands: set 3 synchronize NAME synchronize - Causes the DTS entity to synchronize the clock on the system where the command is entered. SYNOPSIS dtscp synchronize [set clock boolean] ARGUMENTS set clock boolean Specifies whether the clock is abruptly set or gradually adjusted to the computed time. This argument is optional. The following values are valid: false The clock is gradually adjusted. This is the default condition. true The clock is abruptly set. DESCRIPTION The synchronize command causes the DTS clerk or server to solicit time intervals from servers, compute the intersection of the time intervals, and adjust the system clock to the midpoint of the computed time interval. This command overrides the functions of the synchronization hold down characteristic. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The synchronize command does not execute if the entity is already synchronizing or is disabled; the entity must be in the on state. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES 1. The following example shows how to initiate a synchronization for the entity, followed by a gradual clock adjustment: dtscp> synchronize 2. The following example shows how to initiate a synchronization for the entity, followed by an abrupt reset of the clock: dtscp> synchronize set clock true 3 unadvertise NAME unadvertise - Removes the global server entry from the cell profile SYNOPSIS dtscp unadvertise DESCRIPTION The unadvertise command causes DTS to remove the server's name from the cell profile and binding from the related CDS entry, deleting the server's global status. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTE This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES dtscp> unadvertise RELATED INFORMATION Commands: advertise 3 update NAME update - Gradually adjusts the clock on the local node to the specified time SYNOPSIS dtscp update time absolute-time ARGUMENTS time absolute-time Specifies the absolute time to which the clock is adjusted. This argument is required. DESCRIPTION The update command gradually adjusts the system clock to a new time, beginning at the time specified in the argument. The difference between the current clock value and the absolute time specified in the argument is used to adjust the clock. Privilege Required You must have write permission on the ACL associated with the DTS entity in order to execute the command. NOTES The update command is valid only for servers. The combined time and inaccuracy value you specify must be contained within the interval formed by the current time and inaccuracy. That is, the new setting must be more accurate than the current time. This command is replaced at Revision 1.1 by the dcecp command and may not be provided in future releases of DCE. EXAMPLES The following example shows how to update the time for a server; the clock is gradually adjusted to the specified time: dtscp> update time 1993-12-30-11:24:00.000-05:00I0.000 2 dtscp_intro NAME dtscp - DTS control program SYNOPSIS dtscp NOTES With the exception of the following subcommands, this command is replaced at Revision 1.1 by the dcecp command. This command may be fully replaced by the dcecp command in a future release of DCE, and may no longer be supported at that time. + exit + help + quit DESCRIPTION This section describes the commands for the DCE Distributed Time Service (DTS) control program (dtscp). The DTS control program is a command-line interface that enables you to synchronize, adjust, and maintain the system clocks in a distributed network. For a detailed explanation of system clock synchronization and management, see the OSF DCE Administration Guide. The DTS control program commands are + The advertise command, which configures the DTS server as a global server + The change command, which modifies the epoch and sets the local time to a new time + The create command, which establishes a DTS entity (a clerk or server) + The delete command, which causes DTS to exit on the local node + The disable command, which suspends a DTS entity + The enable command, which starts a DTS entity + The exit command, which ends the dtscp management session and returns you to the system prompt + The help command which invokes the dtscp help service. + The quit command, which ends the dtscp management session and returns you to the system prompt + The set command, which modifies characteristics of a DTS entity + The show command, which displays characteristics of a DTS entity + The synchronize command, which synchronizes the system clock with the time obtained from DTS servers in the network + The unadvertise command, which removes the global server entry + The update command, which gradually adjusts the system clock to a new time For more information on any of the above dtscp commands, see the appropriate reference page in this chapter. You can use control program commands from within the control program or from the system prompt. To enter DTS commands from within the control program, first start the control program by entering the dtscp command. For example: $ dtscp dtscp> At this prompt you can enter any control program command; for example: dtscp> show current time To leave the control program and return to the system prompt, enter the exit command. To enter DTS commands from the system prompt (interactively or in a command procedure) enter the dtscp command with an internal command of the control program as the first argument. The control program executes the command without displaying the control program prompt. For example, you can enter the synchronize command as follows: $ dtscp synchronize Some dtscp commands have optional arguments or attributes; there may also be optional variables for the arguments and attributes. See the following sample command: dtscp> update time 1990-08-03-05:45:28.000+01:00I00.500 / / / Command [Argument] Variable -------- [Attribute] Abbreviations You can enter as few as three characters for each DTS command or argument; DTS commands and arguments are unique for three characters or more. For example, rather than entering the command enable set clock true, you can enter the following abbreviated command: dtscp> ena set clo tru Attributes The dtscp set and show commands have several attributes-pieces or sets of data associated with them. The attribute groups are categorized as follows: Characteristics Set or show the entity's operation. Counters Show the number of occurrences of an event since the entity was enabled. Status Show the current state of the entity. (The DTS entity has four status attributes.) Global Servers Show the global servers known by this DTS entity. Local Servers Show the local servers known by this DTS entity. Individual attributes within each of the previously listed groups are described in the reference pages for the set and show commands. The show command also allows you to specify attribute groups. Time Stamps All responses to commands contain a timestamp. The following example shows a typical DTS time display: 1993-03-16-14:29:47.52000-05:00I000.003 The timestamp uses the DTS format that is explained in Chapter 15 of the OSF DCE Administration Guide-Core Components. In this example, the year is 1993, the day is March 16, and the time is 14 hours, 29 minutes, and 47.52 seconds. A negative Time Differential Factor (TDF) of 5 hours and an inaccuracy of 3 milliseconds are included in the timestamp. An inaccuracy value of I----- indicates an infinite inaccuracy. This value appears in time displays before a node's initial synchronization or after you enter the change command without specifying an inaccuracy value. RELATED INFORMATION Commands: advertise change create delete disable enable exit help set show synchronize quit unadvertise update Books: OSF DCE Administration Guide 2 dtsd NAME dtsd - Restarts the DTS daemon SYNOPSIS dtsd [options] [-d] [-w serviceability] dtsd [-s [-k courier|noncourier] [-g] [-o]] dtsd -c ARGUMENTS -d Debug mode. -w serviceability See svcroute for the full description of the appropriate format for this entry. Only the three-field format, severity:how:where, is used. An example is: FATAL:STDERR:FILE:dce_local/var/svc/fatal.log -s Run as a server. Default is backup, courier, local server -g Run dtsd as a global server. -k courier Run dtsd as a courier. -k noncourier Run dtsd as a noncourier. -o When enabling as a server, set the clock immediately. Equivalent to the command enable set clock true in dtscp or to the command dcecp dts activate -abruptly. -c Run dtsd as a clerk. DESCRIPTION The dtsd command restarts the DTS daemon (clerk or server process). When the host system is rebooted, this command is automatically executed as part of the overall DCE configuration procedure. You can enter the command manually if a DTS daemon fails to start automatically upon reboot, or if you want to restart a daemon that you disable and delete to perform a backup or do diagnostic work. After the process starts, you must execute the dtscp commands to create and enable to run DTS. Privilege Required Only the local host machine principal can start the DTS daemon. See the Security reference pages for information about principals. NOTES Use dtsd interactively only when troubleshooting; use the SYS$MANAGER:DCE$SETUP.COM command procedure to start the DTS daemon for all other instances. EXAMPLES To restart the daemon for troubleshooting, follow these steps: 1. Log in to the system. 2. Log in to DCE as the machine principal of the local host. Enter the principal name in the format hosts/hostname/self as shown in the following example command for a host named mystic whose password is smith: $ dce_login hosts/mystic/self smith 3. Enter the following command to see if the required processes are already running: $ @SYS$MANAGER:DCE$SETUP SHOW If the list of active processes does not indicate missing daemons, proceed to step 4. If any process is missing from the list of active processes, enter the following command to start them: $ @SYS$MANAGER:DCE$SETUP START 4. Enter the following command to restart the server: $ STOP/ID= $ dtsd :== $sys$system:dce$dtsd $ dtsd - [-] RELATED INFORMATION Commands: dtscp create enable Books: OSF DCE Administration Guide