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