home *** CD-ROM | disk | FTP | other *** search
/ Oracle Video Server 3.0.3.1 / OVS_3031_NT.iso / win32 / medianet / server / include / ystm.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-07-15  |  4.3 KB  |  107 lines
  1. /* Copyright (c) 1995 by Oracle Corporation.  All Rights Reserved.
  2.  *
  3.  * ystm.h - Time Management
  4.  */
  5.  
  6. #ifndef YSTM_ORACLE
  7. #define YSTM_ORACLE
  8.  
  9. #ifndef SYSX_ORACLE
  10. #include <sysx.h>
  11. #endif
  12.  
  13. EXTC_START
  14.  
  15. typedef struct ystm ystm;                                 /* structured time */
  16.  
  17. /* DISABLE check_naming */
  18. struct ystm
  19. {
  20.   ub4   usec;                                     /* microseconds (0-999999) */
  21.   sword sec;                                               /* seconds (0-59) */
  22.   sword min;                                               /* minutes (0-59) */
  23.   sword hour;                                                /* hours (0-23) */
  24.   sword mday;                                         /* day of month (1-31) */
  25.   sword mon;                                         /* month of year (1-12) */
  26.   sword year;                                                        /* year */
  27.   boolean sign;           /* TRUE if sign is positive (for delta times only) */
  28. };
  29. /* ENABLE check_naming */
  30.  
  31. /*
  32.  * ysClock - get the current time
  33.  *
  34.  * DESCRIPTION
  35.  * ysClock() retrives the current time.  The time is represented as a number
  36.  * of microseconds since some epoch.  The time is returned in clk as a 64-bit
  37.  * signed integer.  This value wraps approximately every 292 thousand years.
  38.  *
  39.  * The time returned by ysClock() is guaranteed to be monotonically increasing
  40.  * throughout the lifetime of the process.  The clock may be based on a
  41.  * hardware tick counter or on a real-time clock.  In the latter case,
  42.  * ysClock() may lose accuracy if the underlying real-time clock is reset by
  43.  * an administrator, but will continue to ensure monotonicity.
  44.  *
  45.  * WARNINGS
  46.  * The granularity of the clock value is usually larger than microseconds.
  47.  *
  48.  * On hosts where no real-time clock is available, the epoch may restart
  49.  * at zero every time the machine is rebooted.  This will affect the calendar
  50.  * time reported by ysConvClock() and ysStrClock().
  51.  *
  52.  * The clock is only guaranteed to be consistent within a single process,
  53.  * although it will almost always be consistent within a single host.  Across
  54.  * hosts, you must use a distributed time facility if synchronized time
  55.  * information is required.
  56.  */
  57. void ysClock(sysb8 *clk);
  58.  
  59. /*
  60.  * ysConvClock, ysConvDelta - convert to structured form
  61.  *
  62.  * DESCRIPTION
  63.  * ysConvClock() converts from a clock value to a structured form.  The result
  64.  * is written to sttm.  The time returned is "local" time.
  65.  *
  66.  * ysConvDelta() converts from a delta clock value to a structured form.
  67.  * A delta clock value is the computed difference between two clock values
  68.  * obtained from ysClock().  The result is written to sttm.  The mon and
  69.  * year fields of sttm are not used.  The mday field contains the number of
  70.  * days (which may represent any number of days to about 89 years before
  71.  * overflow occurs.)
  72.  */
  73. void ysConvClock(sysb8 *clk, ystm *sttm);
  74. void ysConvDelta(sysb8 *clk, ystm *sttm);
  75.  
  76. /*
  77.  * ysStrClock, ysStrDelta - format clock value
  78.  *
  79.  * DESCRIPTION
  80.  * ysStrClock() converts a structured clock value to a canonical string
  81.  * representation of the form: "Jul 10 03:14:30".  The year is added if
  82.  * year is TRUE.  If fraction is not zero, it specifies the number of
  83.  * decimal places that should be included to specify parts of a second.
  84.  * For instance, a value of three will include milliseconds.  Values less
  85.  * than zero or greater than six are reduced to either zero or six, whichever
  86.  * is closer.  The full form is: "Jul 10 03:14:30.123456 1965".  The value
  87.  * is written into the buf parameter, which must be a minimum size of
  88.  * YSTM_BUFLEN.
  89.  *
  90.  * ysStrDelta() converts a structured clock value to a canonical string
  91.  * representation of the form: "sdddd hh:mm:ss.ffffff".  The field "sdddd"
  92.  * is the signed number of days represented by the delta.  If the sign is
  93.  * positive, a blank is used.  The number of fractional digits is
  94.  * indicated by fraction, using the same rules as for ysStrClock(). The
  95.  * value is written into the buf parameter, which must be a minimum size
  96.  * of YSTM_BUFLEN.
  97.  *
  98.  * WARNINGS
  99.  * ysStrClock() is not sensitive to locale.
  100.  */
  101. #define YSTM_BUFLEN 32
  102. char *ysStrClock(char *buf, ystm *sttm, boolean year, sword fraction);
  103. char *ysStrDelta(char *buf, ystm *sttm, sword fraction);
  104.  
  105. EXTC_END
  106. #endif /* YSTM_ORACLE */
  107.