dmGetUST(3dm) dmGetUST(3dm)
dmGetUST, dmGetUSTCurrentTimePair - get digital media Unadjusted System
Time (UST)
#include <dmedia/dmedia.h>
Link with -ldmedia
int dmGetUST(unsigned long long *ust)
int dmGetUSTCurrentTimePair(unsigned long long *ust,
struct timeval *tv)
dmGetUST(3dm) returns a high-resolution, unsigned 64-bit number to
processes using libdmedia. The value of UST is the number of nanoseconds
since the system was booted. Though the resolution is 1 nanosecond, the
actual accuracy may be somewhat lower and varies from system to system.
Unlike other representations of time under UNIX, the value from which
this timestamp derives is never adjusted; therefore it is guaranteed to
be monotonically increasing.
Typically, the UST is used as a timestamp; that is, it is paired with a
specific item or location in a digital media stream. Normally,
dmGetUST(3dm) is not used to do this; each medium has its own method for
obtaining these timestamps. For example, the UST associated with an audio
sample frame number can be obtained using the ALgetframetime(3A) call,
and the UST associated with a video buffer can be obtained using the
vlGetUSTMSCPair(3dm) call. In the MIDI and tserialio libraries, UST
stamps are paired with bytes of data which came in or will go out a
serial port.
The function dmGetUSTCurrentTimePair(3dm) returns a UST measurement and a
time of day measurement (see gettimeofday(3)) which represent the same
instant of time. This is often useful for relating the UST clocks of two
different machines. The usefulness of this function is limited by the
reliability of the UNIX time of day clock, which (unlike the UST clock)
can be adjusted by system administrators and network time daemons.
Both functions return 0 if successful or -1 on error.
Although this function returns an unsigned 64 bit number, most libraries
which manipulate UST (and MSC where appropriate) use the stamp_t symbol,
which is defined as a signed 64-bit number. The signed representation is
generally more convenient, since USTs and MSCs are most often used in
signed arithmetic calculations. We recommend that you cast the value
returned by dmGetUST(3dm) directly into a stamp_t, as in:
stamp_t now;
dmGetUST((unsigned long long *)(&now));
Page 1
dmGetUST(3dm) dmGetUST(3dm)
The period of the 64-bit unsigned UST clock is 584 years, and the period
of the signed 64-bit UST clock is 292 years, so practical code need not
concern itself with UST wrap in either case.
ALintro(3A), ALgetframetime(3A), mdSetOrigin(3dm), mdSend(3dm),
mdReceive(3dm), mdIntro(3dm), vlGetUSTMSCPair(3dm), tserialio(3)
PPPPaaaaggggeeee 2222 [ Back ]
|
