Syntax

#include <utc.h>

int utc_abstime(result, *utc1)

  utc_t result;
  const utc_t *utc1;

Parameters

Input

utc1

Relative binary timestamp.

Output

result

Absolute value of the input relative binary timestamp.

Description

The Absolute Time routine computes the absolute value of a relative binary timestamp. The input timestamp represents a relative (delta) time.

Return Values

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);

Syntax

#include <utc.h>

int utc_addtime(result, *utc1, *utc2)

  utc_t result;
  const utc_t *utc1;
  const utc_t *utc2;

Parameters

Input

utc1

Binary timestamp or relative binary timestamp.

utc2

Binary timestamp or relative binary timestamp.

Output

result

Resulting binary timestamp or relative binary timestamp, depending on the operation performed:

Description

The Add Time 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 represent a relative (delta) time. The TDF in the first input timestamp is copied to the output.

Notes

Although no error is returned, do not use the combination absolute time + absolute time

Return Values

Example

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...
 *  (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

Syntax

#include <utc.h>

int utc_anytime(timetm, *tns, *inacctm, *ins, *tdf, *utc)

   struct tm timetm;
   long *tns;
   struct tm *inacctm;
   long *ins;
   long *tdf;
   const utc_t *utc;

Parameters

Input

utc

Binary timestamp.

Output

timetm

Time component of the binary timestamp expressed in the timestamp’s local time.

tns

Nanoseconds since time component of the binary timestamp.

inacctm

Seconds of 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. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of –1.

ins

Nanoseconds of inaccuracy component of the binary timestamp.

tdf

TDF component of the binary timestamp in units of seconds east or west of GMT.

Description

The Any Time routine converts a binary timestamp to a 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

Example

The following example converts a timestamp, using the TDF information in the timestamp, 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

Syntax

#include <utc.h>

int utc_anyzone(tzname, tzlen, *tdf, isdst, *utc)

   char tzname;
   size_t tzlen;
   long *tdf;
   int *isdst;
   const utc_t *utc;

Parameters

Input

tzlen

Length of the tzname buffer.

utc

Binary time.

Output

tzname

Character string that is long enough to hold the time zone label.

tdf

Longword with differential in seconds east or west 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 Any Zone routine gets the time zone label and offset from GMT, using the TDF contained in the input utc. 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

See the sample program in the Examples section of the utc_anytime routine.

Related Information

Functions: utc_anytime, utc_gmtzone, utc_localzone

Syntax

#include <utc.h>

int utc_ascanytime(*cp, stringlen, *utc)

   char *cp;
   size_t stringlen;
   const utc_t *utc;

Parameters

Input

stringlen

The length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

Description

The ASCII Any Time 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

Example

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

Syntax

#include <utc.h>

int utc_ascgmtime(*cp, stringlen, *utc)

   char *cp;
   size_t stringlen;
   const utc_t *utc;

Parameters

Input

stringlen

Length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

Description

The ASCII GMT Time routine converts a binary timestamp to an ASCII string that expresses a time in GMT.

Return Values

Example

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

Syntax

#include <utc.h>

int utc_asclocaltime(*cp, stringlen, *utc)

   char *cp;
   size_t stringlen;
   const utc_t *utc;

Parameters

Input

stringlen

Length of the cp buffer.

utc

Binary timestamp.

Output

cp

ASCII string that represents the time.

Description

The ASCII Local Time 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).

OpenVMS only: The user selects a time zone by defining sys$timezone_rule, which is created when the sys$manager:net$configure.com is run.

UNIX only: The user selects a time zone by specifying the time zone environment variable. (The reference page for the localtime( ) system call provides additional information.)

If the user’s environment does not specify a time zone rule, the system’s rule is used (details of the rule are system dependent).

OpenVMS only: OpenVMS systems do not have a default time zone rule. You must run the sys$manager:net$configure procedure to specify a time zone.

UNIX only: The rule in /etc/zoneinfo/localtime applies.

Return Values

Example

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

Syntax

#include <utc.h>

int utc_ascreltime(*cp, stringlen, *utc)

   char *cp;
   const size_t stringlen;
   const 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 ASCII Relative Time routine converts a relative binary timestamp to an ASCII string that represents the time.

Return Values

Example

See the sample program in the Examples section of the utc_abstime routine.

Related Information

Functions: utc_mkascreltime

Syntax

#include <utc.h>

int utc_binreltime(*timesp, *inaccsp, *utc)

reltimespec_t *timesp;
timespec_t *inaccsp;
const utc_t *utc;

Parameters

Input

utc

Relative binary timestamp.

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 Binary Relative Time 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

Example

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

Syntax

#include <utc.h>

int utc_bintime(*timesp, *inaccsp, *tdf, *utc)

   timespec_t *timesp;
   timespec_t *inaccsp;
   long *tdf;
   const utc_t *utc;

Parameters

Input

utc

Binary timestamp.

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 or west of GMT.

Decsription

The Binary Time routine converts a binary timestamp to a timespec structure. The TDF information contained in the timestamp is returned.

Return Values

Example

See the sample program in the Examples section of the utc_anytime routine.

Related Information

Functions: utc_binreltime, utc_mkbintime

Syntax

#include <utc.h>

int utc_boundtime(*result, *utc1, *utc2)

   utc_t *result;
   const utc_t *utc1;
   const utc_t *utc2;

Parameters

Input

utc1

Before binary timestamp or relative binary timestamp.

utc2

After binary timestamp or relative binary timestamp.

Output

result

Spanning timestamp.

Description

Given two UTC times, the Bound Time 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. If one or both input values have infinite inaccuracies, the returned time value also has an infinite inaccuracy and is the average of the two input values.

Return Values

Example

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).

OpenVMS: The user selects a time zone by defining sys$timezone_rule, which is created when the sys$manager:net$configure.com is run.

UNIX: The user selects a time zone by specifying the time zone environment variable. (The reference page for the localtime( ) system call provides additional information.)

If the user’s environment does not specify a time zone rule, the system’s rule is used (details of the rule are system dependent).

OpenVMS: OpenVMS systems do not have a default time zone rule. You must run the sys$manager:net$configure procedure to specify a time zone.

UNIX: The rule in /etc/zoneinfo/localtime 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

Syntax

      #include <utc.h>

      int utc_cmpintervaltime(*relation, *utc1, *utc2)

         enum utc_cmptype *relation;
         const utc_t *utc1;
         const utc_t *utc2;

Parameters

Input

utc1

Binary timestamp or relative binary timestamp.

utc2

Binary timestamp or relative binary timestamp.

Output

relation

Receives the result of the comparison of utc1:utc2, where the result is an enumerated type with one of the following values:

Description

The Compare Interval Time 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 and binary timestamps. If you do, no meaningful results and no errors are returned.

This 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

Return Values

Example

The following example checks to see if the current time is definitely after 1:00 P.M. today GMT.

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               */

/*
 *   Construct a tm structure that corresponds to 1:00 PM...
 */

tmtime.tm_hour = 13;
tmtime.tm_min = 0;
tmtime.tm_sec = 0;

/*
 *   Convert to a binary timestamp...
 */

utc_mkgmtime(&testtime,  /* Out: Binary timestamp of 1:00 PM  */
             &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, noting the use of the
 *   NULL argument...
 */

utc_cmpintervaltime(&relation,    /* Out: Comparison relation */
                    (utc_t *)0,   /* In:  Current timestamp   */
                    &testtime);   /* In:  1:00 PM timestamp   */

/*
 *   If it is not later - wait, print a message, etc.
 */

if (relation != utc_greaterThan) {

/*
 *     Note: It could be earlier than 1:00 PM or it could be
 *           indeterminate. If indeterminate, for some applications
 *           it might be worth waiting.
 */
}

Related Information

Functions: utc_cmpmidtime

Syntax

#include <utc.h>

int utc_cmpmidtime(*relation, *utc1, *utc2)

   enum utc_cmptype *relation;
   const utc_t *utc1;
   const utc_t *utc2;

Parameters

Input

utc1

Binary timestamp or relative binary timestamp.

utc2

Binary timestamp or relative binary timestamp.

Output

relation

Result of the comparison of utc1:utc2, where the result is an enumerated type with one of the following values:

Description

The Compare Midpoint Times 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 and 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

Example

The following example checks if the current time (ignoring inaccuracies) is after 1:00 P.M. today 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               */

/*
 *   Construct a tm structure that corresponds to 1:00 P.M....
 */

tmtime.tm_hour = 13;
tmtime.tm_min = 0;
tmtime.tm_sec = 0;

/*
 *   Convert to a binary timestamp...
 */

utc_mklocaltime(&testtime, /* Out: Binary timestamp of 1:00 P.M. */
                &tmtime,   /* In:  1:00 P.M. 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, noting the use of the
 *   NULL argument...
 */

utc_cmpmidtime(&relation,    /* Out: Comparison relation         */
               (utc_t *)0,   /* In:  Current timestamp           */
               &testtime);   /* In:  1:00 P.M. timestamp         */

/*
 *   If the time is not later - wait, print a message, etc.
 */

if (relation != utc_greaterThan) {

/*          It is not later then 1:00 P.M. local time. Note that
 *          this depends on the setting of the user's environment.
 */
}

Related Information

Functions: utc_cmpintervaltime

Syntax

#include <utc.h>

int utc_gettime(*utc)

   utc_t *utc;

Parameters

Input

None.

Output

utc

System time as a binary timestamp.

Description

The Get Time 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

Example

See the sample program in the Examples section of the utc_binreltime routine.

Syntax

#include <utc.h>

int utc_getusertime(*utc)

   utc_t *utc;

Parameters

Input

None.

Output

utc

System time as a binary timestamp.

Description

The Get User Time 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).

OpenVMS: The user selects a time zone by defining sys$timezone_rule, which is created when the sys$manager:net$configure.com is run.

UNIX: The user selects a time zone by specifying the time zone environment variable. (The reference page for the localtime( ) system call provides additional information.)

If the user’s 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).

OpenVMS: OpenVMS systems do not have a default time zone rule. You must run the sys$manager:net$configure procedure to specify a time zone.

UNIX: The rule in /etc/zoneinfo/localtime applies.

Return Values

Example

See the sample program in the Examples section of the utc_boundtime routine.

Related Information

Functions: utc_gettime

Syntax

#include <utc.h>

int utc_gmtime(*timetm, *tns, *inacctm, *ins, *utc)

   struct tm *timetm;
   long *tns;
   struct tm *inacctm;
   long *ins;
   const utc_t *utc;

Parameters

Input

utc

Binary timestamp to be converted to tm structure components.

Output

timetm

Time component of the binary timestamp.

tns

Nanoseconds since time component of the binary timestamp.

inacctm

Seconds of 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 zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of –1.

ins

Nanoseconds of inaccuracy component of the binary timestamp. If the inaccuracy is infinite, ins returns a value of –1.

Description

The Greenwich Mean Time (GMT) 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

Example

See the sample program in the Examples section of the utc_cmpintervaltime routine.

Related Information

Functions: utc_anytime, utc_gmtzone, utc_localtime, utc_mkgmtime

Syntax

#include <utc.h>

int utc_gmtzone(*tzname, tzlen, *tdf, *isdst, *utc)

   char *tzname;
   size_t tzlen;
   long *tdf;
   int *isdst;
   const 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 or west of GMT. A value of zero is always returned.

isdst

Integer with a value of zero, indicating that daylight saving time is not in effect. A value of zero is always returned.

Description

The Greenwich Mean Time Zone 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 Any Zone (utc_anyzone) and the Local Zone (utc_localzone) routines.

Notes

All of the output parameters are optional. No value is returned and no error occurs if the tzname pointer is NULL.

Return Values

Example

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    */
              &now);          /* In:  Current binary timestamp */

/*
 *   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     */

/*
 *   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

Syntax

#include <utc.h>

int utc_localtime(*timetm, *tns, *inacctm, *ins, *utc)

   struct tm *timetm;
   long *tns;
   struct tm *inacctm;
   long *ins;
   const utc_t *utc;

Parameters

Input

utc

Binary timestamp.

Output

timetm

Time component of the binary timestamp, expressing local time.

tns

Nanoseconds since time component of the binary timestamp.

inacctm

Seconds of 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 zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of –1.

ins

Nanoseconds of inaccuracy component of the binary timestamp. If the inaccuracy is infinite, ins returns a value of –1.

Description

The Local Time 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).

OpenVMS: The user selects a time zone by defining sys$timezone_rule, which is created when the sys$manager:net$configure.com is run.

UNIX: The user selects a time zone by specifying the time zone environment variable. (The reference page for the localtime() system call provides additional information.)

If the user’s environment does not specify a time zone rule, the system’s rule is used (details of the rule are system dependent).

OpenVMS: OpenVMS systems do not have a default time zone rule. You must run the sys$manager:net$configure procedure to specify a time zone.

UNIX: The rule in /etc/zoneinfo/localtime applies.

Additional returns include nanoseconds since time and nanoseconds of inaccuracy.

Return Values

Example

See the sample program in the Examples section of the utc_gmtzone routine.

Related Information

Functions: utc_anytime, utc_gmtime, utc_localzone, utc_mklocaltime

Syntax

#include <utc.h>

int utc_localzone(*tzname, tzlen, *tdf, *isdst, *utc)

   char *tzname;
   size_t tzlen;
   long *tdf;
   int *isdst;
   const utc_t *utc;

#include <utc.h>

int utc_localzone(*tzname, tzlen, *tdf, *isdst, *utc)

Parameters

Input

tzlen

Length of the tzname buffer.

utc

Binary timestamp.

Output

tzname

Character string long enough to hold the time zone label.

tdf

Longword with differential in seconds east or west of GMT.

isdst

Integer with a value of zero if standard time is in effect or a value of 1 if daylight savings time is in effect.

Description

The Local Zone 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).

OpenVMS: The user selects a time zone by defining sys$timezone_rule, which is created when the sys$manager:net$configure.com is run.

UNIX: The user selects a time zone by specifying the time zone environment variable. (The reference page for the localtime( ) system call provides additional information.)

If the user’s environment does not specify a time zone rule, the system’s rule is used (details of the rule are system dependent).

OpenVMS: OpenVMS systems do not have a default time zone rule. You must run the sys$manager:net$configure procedure to specify a time zone.

UNIX: The rule in /etc/zoneinfo/localtime applies.

Notes

All of the output parameters are optional. No value is returned and no error occurs if the pointer is null.

Return Values

Example

See the sample program in the Examples section of the utc_gmtzone routine.

Related Information

Functions: utc_anyzone, utc_gmtzone, utc_localtime

Syntax

#include <utc.h>

int utc_mkanytime(*utc, *timetm, tns, *inacctm, ins, tdf)

   utc_t *utc;
   const struct tm *timetm;
   long tns;
   const 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.

tns

Nanoseconds since time component.

inacctm

A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite; tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored on input.

ins

Nanoseconds of inaccuracy component.

tdf

Time differential factor to use in conversion.

Output

utc

Resulting binary timestamp.

Description

The Make Any Time 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

Example

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

Syntax

#include <utc.h>

int utc_mkascreltime(*utc, *string)

   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 Make ASCII Relative Time 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

Example

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 sec. 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

Syntax

#include <utc.h>

int utc_mkasctime(*utc, *string)

   utc_t *utc;
   char *string;

Parameters

Input

string

A null-terminated string that expresses an absolute time.

Output

utc

Resulting binary timestamp.

Description

The Make ASCII Time 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

Example

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:00 I 3600.32");

utc_mkasctime(&utc,    /* Out: Binary utc  */
              str);    /* In:  String      */

Related Information

Functions: utc_ascanytime, utc_ascgmtime, utc_asclocaltime

Syntax

#include <utc.h>

int utc_mkbinreltime(*utc, *timesp, *inaccsp)

   utc_t *utc;
   const reltimespec_t *timesp;
   const timespec_t *inaccsp;

Parameters

Input

timesp

A reltimespec structure that expresses a relative time.

inaccsp

A timespec structure that expresses inaccuracy. If tv_sec is set to a value of –1, the inaccuracy is considered to be infinite.

Output

utc

Resulting relative binary timestamp.

Description

The Make Binary Relative Time routine converts a timespec structure that expresses relative time to a binary timestamp.

Return Values

Example

See the sample program in the Examples section of the utc_addtime routine.

Related Information

Functions: utc_binreltime, utc_mkbintime

Syntax

#include <utc.h>

int utc_mkbintime(*utc, *timesp, *inaccsp)

   utc_t *utc;
   const timespec_t *timesp;
   const 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 tv_sec is set to a value of –1, the inaccuracy is considered to be infinite.

tdf

TDF component of the binary timestamp.

Output

utc

Resulting binary timestamp.

Description

The Make Binary Time routine converts a timespec structure time to a binary timestamp. The TDF input is used as the TDF of the binary timestamp.

Return Values

Example

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

Syntax

#include <utc.h>

int utc_mkgmtime(*utc, *timetm, tns, *inacctm, ins)

   utc_t *utc;
   const struct tm *timetm;
   long tns;
   const struct tm *inacctm;
   long ins;

Parameters

Input

timetm

A tm structure that expresses GMT. On input, tm_wday and tm_yday are ignored.

tns

Nanoseconds since time component.

inacctm

A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite. On input, tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored.

ins

Nanoseconds of inaccuracy component.

Output

utc

Resulting binary timestamp.

Description

The Make Greenwich Mean Time 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

Example

See the sample program in the Examples section of the utc_cmpintervaltime routine.

Related Information

Functions: utc_gmtime

Syntax

#include <utc.h>

int utc_mklocaltime(*utc, *timetm, tns, *inacctm, ins)

   utc_t *utc;
   const struct tm *timetm;
   long tns;
   const 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.

tns

Nanoseconds since time component.

inacctm

A tm structure that expresses days, hours, minutes, and seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite. On input, tm_mday, tm_mon, tm_wday, tm_isdst, tm_gmtoff, and tm_zone are ignored.

ins

Nanoseconds of inaccuracy component.

Output

utc

Resulting binary timestamp.

Description

The Make Local Time 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).

OpenVMS: The user selects a time zone by defining sys$timezone_rule, which is created when the sys$manager:net$configure.com is run.

UNIX: The user selects a time zone by specifying the time zone environment variable. (The reference page for the localtime( ) system call provides additional information.)

If the user’s environment does not specify a time zone rule, the system’s rule is used (details of the rule are system dependent).

OpenVMS: OpenVMS systems do not have a default time zone rule. You must run the sys$manager:net$configure procedure to specify a time zone.

UNIX: The rule in /etc/zoneinfo/localtime applies.

Additional inputs include nanoseconds since the last second of time and nanoseconds of inaccuracy.

Return Values

Example

See the sample program in the Examples section of the utc_cmpmidtime routine.

Related Information

Functions: utc_localtime

Syntax

#include <utc.h>

int utc_mkreltime(*utc, *timetm, tns, *inacctm, ins)

   utc_t *utc;
   const struct tm *timetm;
   long tns;
   const 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.

tns

Nanoseconds since time component.

inacctm

A tm structure that expresses seconds of inaccuracy. If tm_yday is negative, the inaccuracy is considered to be infinite. On input, tm_mday, tm_mon, tm_year, tm_wday, tm_isdst, and tm_zone are ignored.

ins

Nanoseconds of inaccuracy component.

Output

utc

Resulting relative binary timestamp.

Description

The Make Relative Time 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

Example

The following example converts a string relative time in the format (1991-04-01- 12:12:12.12I12.12) to a binary timestamp. This may be part of an input relative timestamp routine, though a real implementation will include range checking.

utc_t       utc;
struct tm   tmtime, tminacc;
float       tsec, isec;
double      tmp;
long        tnsec, insec;
int         i, tzhour, tzmin, year, mon;
char        *string;

/*
 *   Try to convert the string...
 */

if(sscanf(string, "%d-%d-%d-%d:%d:%eI%e",
          &year, &mon, &tmtime.tm_mday, &tmtime.tm_hour,
          &tmtime.tm_min, &tsec, &isec) != 7) {

/*
 *   ERROR...
 */
    exit(1);

}

/*
 *   Fill in the fields...
 */

tmtime.tm_year = year - 1900;
tmtime.tm_mon = --mon;
tmtime.tm_sec = tsec;
tnsec = (modf(tsec, &tmp)*1.0E9);
tminacc.tm_sec = isec;
insec = (modf(isec, &tmp)*1.0E9);

/*
 * Convert to a binary timestamp...
 */

utc_mkreltime(&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          */

Related Information

Functions: utc_reltime

Syntax

#include <utc.h>

int utc_mkvmsanytime(*utc, *timadr, tdf)

   utc_t *utc;
   const long *timadr;
   const long tdf;

Parameters

Input

*timadr

Binary OpenVMS format time.

tdf

Time differential factor to use in conversion.

Output

*utc

Binary timestamp.

Description

The Make VMS Any Time routine converts a binary time in the OpenVMS (Smithsonian) format and an arbitrary TDF to a UTC-based binary timestamp. Because the input and output values are based on different time standards, any input representing a value after A.D. 30,000 returns an error.

Return Values

Example

The following example shows how to convert between OpenVMS format binary timestamps and UTC binary timestamps, while specifying the TDF for each. The TDF value determines the offset from GMT and the local time.

/*****
 start example mkvmsanytime,vmsanytime
 *****/
#include <utc.h>

main()
{
struct utc utcTime;
int vmsTime[2];

SYS$GETTIM(vmsTime);    /* read the current time */

/*
 * convert the VMS local time to a UTC, applying a TDF of
 * -300 minutes (the timezone is -5 hours from GMT)
 */
if (utc_mkvmsanytime(&utcTime,vmsTime,-300))
    exit(1);

/*
 * convert UTC back to VMS local time.  A TDF of -300 is applied
 * to the UTC, since utcTime was constructed with that same value.
 * This effectively gives us the same VMS time value we started
 * with.
 */
if (utc_vmsanytime(vmsTime,&utcTime))
    exit(2);
}
/****
  end example
 ****/

Related Information

Function: utc_vmsanytime

Parameters

Input

*timadr

Binary OpenVMS format time representing GMT or the UTC equivalent.

Output

*utc

Binary timestamp.

Description

The Make VMS Greenwich Mean Time routine converts an OpenVMS format binary time representing GMT to a binary timestamp with the equivalent UTC value. Since the input and output values are based on different time standards, any input representing a value after A.D. 30,000 returns an error.

Example

See the sample program in the Examples section of the vmsgmtime routine.

Related Information

Function: utc_vmsgmtime

Syntax

#include <utc.h>

int utc_mkvmslocaltime(*utc, *timadr)

   const long *timadr;
   utc_t *utc;

Parameters

Input

*timadr

Binary OpenVMS format time expressing local time.

Output

*utc

Binary timestamp expressing the system’s local time.

Description

The Make VMS Local Time routine converts a binary OpenVMS format time, representing the local time of the host system, to a binary timestamp. The system’s local time value is defined by the time zone rule in sys$timezone_rule, which is created by the system configuration process sys$manager:net$configure.com.

Notes

If the routine call is made during a seasonal time zone change when the local time is indeterminate, an error is returned. For example, if the time zone change occurs at the current local time of 2:00 A.M. to a new local time of 1:00 A.M., and the routine is called between 1:00 A.M. and 2:00 A.M., it cannot be determined which TDF applies.

Return Values

Example

The following example shows how to retrieve the current local time of the system in the binary OpenVMS format, convert the OpenVMS format time to a UTC-based binary timestamp (using the system’s TDF), and print an ASCII representation of the binary timestamp.

/*********
  start example mkvmslocaltime
 *********/
#include <utc.h>

main()
{
char outstring[UTC_MAX_STR_LEN];
struct utc utcTime;
int vmsTime[2];

SYS$GETTIM(vmsTime);                      /* read current time      */

if (utc_mkvmslocaltime(&utcTime,vmsTime)) /* convert the local time */
    exit(1);                              /* vmsTime to UTC using   */
                                          /* the system tdf.        */

Related Information

Function: utc_vmslocaltime

Syntax

#include <utc.h>

int utc_mulftime(*result, *utc1, factor)

   utc_t *result;
   const utc_t *utc1;
   const double factor;

Parameters

Input

utc1

Relative binary timestamp.

factor

Real scale factor (double-precision floating-point) (G format floating-point on VAX systems).

Output

result

Resulting relative binary timestamp.

Description

The Multiply a Relative Time by a Real Factor 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

Example

The following example scales and prints a relative time.

utc_t       relutc, scaledutc;
struct tm   sacledreltm;
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:  Length of input str */
               &scaledutc);      /* In:  Rel time to convert */

printf("%s\n",timstr);

/*
 *   Scale it by a factor of 17.65...
 */

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 str 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

Syntax

#include <utc.h>

int utc_multime(*result, *utc1, factor)

   utc_t *result;
   const utc_t *utc1;
   long factor;

Parameters

Input

utc1

Relative binary timestamp.

factor

Integer scale factor.

Output

result

Resulting relative binary timestamp.

Description

The Multiply Relative Time by an Integer Factor 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

Example

See the sample program in the Examples section of the utc_mulftime routine.

Related Information

Functions: utc_mulftime

Syntax

#include <utc.h>

int utc_pointtime(*utclp, *utcmp, *utchp, *utc)

   utc_t *utclp;
   utc_t *utcmp;
   utc_t *utchp;
   const utc_t *utc;

Parameters

Input

utc

Binary timestamp or relative binary timestamp.

Output

utclp

Lowest (earliest) possible time that the input binary timestamp or shortest possible relative time that the relative binary timestamp can represent.

utcmp

Midpoint of the input binary timestamp or the midpoint of the input relative binary timestamp.

utchp

Highest (latest) possible time that the input binary timestamp or the longest possible relative time that the relative binary timestamp can represent.

Description

The Point Time 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 infinite inaccuracy.

Return Values

Example

See the sample program in the Examples section of the utc_addtime routine.

Related Information

Functions: utc_boundtime, utc_spantime

Syntax

#include <utc.h>

int utc_reltime(*timetm, *tns, *inacctm, *ins, *utc)

   struct tm *timetm;
   long *tns;
   struct tm *inacctm;
   long *ins;
   const 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 zero. The field tm_yday contains the number of days of relative time.

tns

Nanoseconds since time component of the relative binary timestamp.

inacctm

Seconds of 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 zero. The field tm_yday contains the inaccuracy in days. If the inaccuracy is infinite, all tm structure fields return values of –1.

ins

Nanoseconds of inaccuracy component of the relative binary timestamp.

Description

The Relative Time routine converts a relative binary timestamp to a tm structure. Additional returns include nanoseconds since time and nanoseconds of inaccuracy.

Return Values

Example

See the sample program in the Examples section of the utc_mulftime routine.

Related Information

Functions: utc_mkreltime

Syntax

#include <utc.h>

int utc_spantime(*result, *utc1, *utc2)

   utc_t *result;
   const utc_t *utc1;
   const utc_t *utc2;

Parameters

Input

utc1

Binary timestamp.

utc2

Binary timestamp.

Output

result

Spanning timestamp.

Description

Given two binary timestamps, the Span Time 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 in the output UTC value is copied from the utc2 input. If either input binary timestamp has an infinite inaccuracy, an error is returned.

Return Values

Example

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 possible time...
 */

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

Syntax

#include <utc.h>

int utc_subtime(*result, *utc1, *utc2)

   utc_t *result;
   const utc_t *utc1;
   const utc_t *utc2;

Parameters

Input

utc1

Binary timestamp or relative binary timestamp.

utc2

Binary timestamp or relative binary timestamp.

Output

result

Resulting binary timestamp or relative binary timestamp, depending on the operation performed:

Description

The Subtract Time routine subtracts one binary timestamp from another.

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, do not use the combination relative time

Return Values

Example

See the sample program in the Examples section of the utc_binreltime routine.

Related Information

Functions: utc_addtime

Syntax

#include <utc.h>

int utc_vmsanytime(*timadr, *utc)

   const utc_t *utc;
   long *timadr;

Parameters

Input

*utc

Binary timestamp.

Output

*timadr

Binary OpenVMS format time.

Description

The VMS Any Time routine converts a UTC-based binary timestamp to a 64-bit binary time in the OpenVMS (Smithsonian) format. Because the input and output values are based on different time standards, any input representing a value before the Smithsonian base time of November 17, 1858 returns an error.

Return Values

Example

See the sample program in the Examples section of the mkvmsanytime routine.

Related Information

Function: utc_mkvmsanytime

Syntax

#include <utc.h>

int utc_vmsgmtime(*timadr, *utc)

   const utc_t *utc;
   long *timadr;

Parameters

Input

*utc

Binary timestamp to be converted.

Output

*timadr

Binary OpenVMS format time representing GMT or the UTC equivalent.

Description

The OpenVMS Greenwich Mean Time routine converts a UTC-based binary timestamp to a 64-bit binary time in the OpenVMS (Smithsonian) format. The OpenVMS format time represents Greenwich Mean Time or the equivalent UTC. Because the input and output values are based on different time standards, any input representing a value before the Smithsonian base time of November 17, 1858 returns an error.

Return Values

Example

The following example shows the following time zone and time format conversions:

/*****
  start example vmsgmtime, mkvmsgmtime, vmslocaltime
 *****/
#include <utc.h>

main()
{
int status;
struct utc utcTime;
int vmsTime[2];

 if (!((status=SYS$GETUTC(&utcTime))&1))
     exit(status);              /* read curr time as a utc */

/*
 * convert the utcvalue into a vms time, with a timezone of 0
 * (GMT).  Printing the resultant vmstime yields the time at
 * the prime meridian in Greenwich, not (necessarily) the
 * local time.
 */
 if (utc_vmsgmtime(vmsTime,&utcTime))
    exit(1);

/*
 * Convert the vmstime (which is in GMT) to a utc
 */
if (utc_mkvmsgmtime(&utcTime, vmsTime))
    exit(2);

/*
 *  convert the UTC to local 64-bit time.  Note that this is the
 *  value we would have read if we had issued a 'SYS$GETTIM' in
 *  the initial statement.
 */
if (utc_vmslocaltime(vmsTime, &utcTime))
    exit(3);
}
/*****
 end example
     *****/

Related Information

Function: utc_mkvmsgmtime

Syntax

#include <utc.h>

int utc_vmslocaltime(*timadr, *utc)

   const utc_t *utc;
   long *timadr;

Parameters

Input

*utc

Binary timestamp.

Output

*timadr

Binary OpenVMS format time expressing local time.

Description

The VMS Local Time routine converts a binary timestamp to a binary OpenVMS format time; the output value represents the local time of the host system. The system’s offset from UTC and the local time value are defined by the time zone rule in sys$timezone_rule, which is created by the system configuration process sys$manager:net$configure.com.

Return Values

Example

See the sample program in the Examples section of the vmsgmtime routine.

Related Information

Function: utc_vmsmklocaltime