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 infor-
mation 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
1 – 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.
2 – utc_abstime
NAME
utc_abstime - Computes the absolute value of a relative binary
timestamp
SYNOPSIS
#include <dce/utc.h>
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 <dce/utc.h>
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 time-
stamp 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
4 – utc_anytime
NAME
utc_anytime - Converts a binary timestamp to a tm structure
SYNOPSIS
#include <dce/utc.h>
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
5 – utc_anyzone
NAME
utc_anyzone - Gets the time zone label and offset from GMT
SYNOPSIS
#include <dce/utc.h>
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
6 – utc_ascanytime
NAME
utc_ascanytime - Converts a binary timestamp to an ASCII string that
represents an arbitrary time zone
SYNOPSIS
#include <dce/utc.h>
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
7 – utc_ascgmtime
NAME
utc_ascgmtime - Converts a binary timestamp to an ASCII string that
expresses a GMT time
SYNOPSIS
#include <dce/utc.h>
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
8 – utc_asclocaltime
NAME
utc_asclocaltime - Converts a binary timestamp to an ASCII string that
represents a local time
SYNOPSIS
#include <dce/utc.h>
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
9 – utc_ascreltime
NAME
utc_ascreltime - Converts a relative binary timestamp to an ASCII
string that represents the time
SYNOPSIS
#include <dce/utc.h>
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
10 – utc_binreltime
NAME
utc_binreltime - Converts a relative binary timestamp to two timespec
structures that express relative time and inaccuracy
SYNOPSIS
#include <dce/utc.h>
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
11 – utc_bintime
NAME
utc_bintime - Converts a binary timestamp to a timespec structure
SYNOPSIS
#include <dce/utc.h>
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
12 – 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 <dce/utc.h>
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
13 – utc_cmpintervaltime
NAME
utc_cmpintervaltime - Compares two binary timestamps or two relative
binary timestamps
SYNOPSIS
#include <dce/utc.h>
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
14 – utc_cmpmidtime
NAME
utc_cmpmidtime - Compares two binary timestamps or two relative binary
timestamps, ignoring inaccuracies
SYNOPSIS
#include <dce/utc.h>
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
15 – utc_gettime
NAME
utc_gettime - Returns the current system time and inaccuracy as a
binary timestamp
SYNOPSIS
#include <dce/utc.h>
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.
16 – utc_getusertime
NAME
utc_getusertime - Returns the time and process-specific TDF, rather
than the system-specific TDF
SYNOPSIS
#include <dce/utc.h>
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
17 – utc_gmtime
NAME
utc_gmtime - Converts a binary timestamp to a tm structure that
expresses GMT or the equivalent UTC
SYNOPSIS
#include <dce/utc.h>
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
18 – utc_gmtzone
NAME
utc_gmtzone - Gets the time zone label for GMT
SYNOPSIS
#include <dce/utc.h>
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
19 – utc_localtime
NAME
utc_localtime - Converts a binary timestamp to a tm structure that
expresses local time
SYNOPSIS
#include <dce/utc.h>
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
20 – utc_localzone
NAME
utc_localzone - Gets the local time zone label and offset from GMT,
given utc
SYNOPSIS
#include <dce/utc.h>
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
21 – 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 <dce/utc.h>
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 (express-
ing 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
22 – utc_mkascreltime
NAME
utc_mkascreltime - Converts a NULL-terminated character string that
represents a relative timestamp to a binary
timestamp
SYNOPSIS
#include <dce/utc.h>
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
23 – utc_mkasctime
NAME
utc_mkasctime - Converts a NULL-terminated character string that
represents an absolute timestamp to a binary
timestamp
SYNOPSIS
#include <dce/utc.h>
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
24 – utc_mkbinreltime
NAME
utc_mkbinreltime - Converts a timespec structure expressing a
relative time to a binary timestamp
SYNOPSIS
#include <dce/utc.h>
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
25 – utc_mkbintime
NAME
utc_mkbintime - Converts a timespec structure to a binary timestamp
SYNOPSIS
#include <dce/utc.h>
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
26 – utc_mkgmtime
NAME
utc_mkgmtime - Converts a tm structure that expresses GMT or UTC
to a binary timestamp
SYNOPSIS
#include <dce/utc.h>
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
27 – utc_mklocaltime
NAME
utc_mklocaltime - Converts a tm structure that expresses local time
to a binary timestamp
SYNOPSIS
#include <dce/utc.h>
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
28 – utc_mkreltime
NAME
utc_mkreltime - Converts a tm structure that expresses relative time
to a relative binary timestamp
SYNOPSIS
#include <dce/utc.h>
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 */
29 – utc_mulftime
NAME
utc_mulftime - Multiplies a relative binary timestamp by a
floating-point value.
SYNOPSIS
#include <dce/utc.h>
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
30 – utc_multime
NAME
utc_multime - Multiplies a relative binary timestamp by an integer
factor
SYNOPSIS
#include <dce/utc.h>
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
31 – utc_pointtime
NAME
utc_pointtime - Converts a binary timestamp to three binary
timestamps that represent the earliest, most
likely, and latest time
SYNOPSIS
#include <dce/utc.h>
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
32 – utc_reltime
NAME
utc_reltime - Converts a relative binary timestamp to a tm structure
SYNOPSIS
#include <dce/utc.h>
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
33 – 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 <dce/utc.h>
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
34 – utc_subtime
NAME
utc_subtime - Computes the difference between two binary timestamps
SYNOPSIS
#include <dce/utc.h>
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