SCO OpenServer

# TICKS(D3oddi)

**TICKS --
macros for lbolt values
**

## Synopsis

#include <sys/types.h>
#include <sys/btok.h>
clock_t TICKS(void);

clock_t TICKS_BETWEEN(clock_t t1, clock_t t2);

clock_t TICKS_SINCE(clock_t t);

## Description

The
**TICKS**( )
macros allow access to and comparison of
**lbolt**
values.
The **lbolt** global variable
should never be referenced directly,
nor should saved **lbolt** values be compared
except with these macros.
### Arguments

*start_ticks*, *end_ticks*-
**lbolt** values as returned by the
**TICKS**( )
macro.

### Return values

The following macros return absolute **lbolt** values:

**TICKS**-
Returns the current
**lbolt** value,
which is the time in ticks since the system was booted.
A tick is an implementation-dependent time period,
typically 1/100 of a second.
Drivers should not build in any assumptions
about the length of a tick,
but can convert between ticks and microseconds using the
a calculation with the **Hz** kernel variable
that represents the approximate number of ticks per second.

The lbolt counter underlying
**TICKS**( )
is of finite size and will wrap around
if the system stays up long enough.
At any given moment,
only times in the range:

[current_lbolt - ULONG_MAX] through [current_lbolt + ULONG_MAX]

can be represented.
**ULONG_MAX** is discussed in
``CLOCK_MAX'' in *HDK Technical Reference*.
Assuming 100 ticks-per-second,
this is a range of 497 days,
248 before and 248 after the current day.
The representation is signed;
these macros can return a value
that is negative, zero, or positive.
The following macros compare **lbolt** values:

**TICKS_BETWEEN**-
Returns the elapsed time in ticks between
the two times represented by the arguments.
If
*start_ticks* and *end_ticks*
represent times more than **ULONG_MAX** ticks apart,
or *end_ticks* precedes *start_ticks*,
the result is undefined.

**TICKS_SINCE**-
Returns the elapsed time in ticks that has passed
since the time represented by
*start_ticks*.
The result is undefined
if *start_ticks* represents a future time
or a time more than **ULONG_MAX** ticks in the past.

## Usage

**TICKS**( )
and
**TICKS_SINCE**( )
suffice to deal with most needs
for which drivers have traditionally used
the **lbolt** variable.
A common paradigm is:
start_time = TICKS();
/* ...*perform some device operation*... */

if (TICKS_SINCE(start_time) > timeout_ticks) {
/* *operation took too long* */
}

Performance instrumentation code
will often contain sequences such as:
start_time = TICKS();
/* ...*perform some device operation*... */

/* *see how long the operation took, in microseconds* */
interval = (TICKS_SINCE(start_time)/Hz);

**TICKS_BETWEEN**( )
is seen less often,
and then usually to perform the same calculation as
**TICKS_SINCE**( )
when the current **lbolt** value
is already available from another source, as in:
interval = (TICKS_BETWEEN(start_time, current_lbolt)/Hz);

Do not use any value, including zero,
to represent a special case
when interpreting the return values of the
**TICKS**( ),
macro, since it will periodically return that value
if the system stays up indefinitely.

See
``lbolt'' in *HDK Technical Reference*
for more details about pitfalls involved
when doing arithmetic manipulations and comparisons
of **lbolt** values.

### Context and synchronization

All
contexts.
### Version applicability

oddi:
5, 5mp, 6, 6mp
### Differences between versions

ODDI versions prior to version 5
do not support the
**TICKS**( )
family of macros.
Drivers must access the **lbolt** variable directly,
being sure to use it correctly; see
``lbolt'' in *HDK Technical Reference*.
### Future directions

The **lbolt** global variable may be eliminated
in a future release.
### SVR5 DDI compatibility

These same macros are supported in DDI 8
and later versions.
See the
**TICKS**(D3)
manual page for details.
Minor coding modifications are required to use
**drv_hztousec**(D3)
rather than calculations involving the **Hz** variable,
and the **ULONG_MAX** constant
is replaced by the **CLOCK_MAX** constant.
DDI 8 also supports two additional macros,
**TICKS_FARPAST**( )
and
**TICKS_FARFUTURE**( ),
that are not supported for ODDI drivers.

## References

**TICKS**(D3)
``CLOCK_MAX'' in *HDK Technical Reference*

``lbolt'' in *HDK Technical Reference*

*
19 June 2005
*

© 2005 The SCO Group, Inc. All rights reserved.

OpenServer 5 HDK - June 2005