TRACE_ON(3x,L)              AIX Technical Reference              TRACE_ON(3x,L)



-------------------------------------------------------------------------------
trace_on



PURPOSE

Checks whether trace channel is enabled.

LIBRARY

Run-time Services Library (librts.a)

SYNTAX

int trace_on (chanmask)
unsigned long chanmask;

DESCRIPTION

The trace_on subroutine queries the application trace device driver to
determine whether a given trace channel is enabled.  trace_on allows a program
to avoid the unnecessary overhead of setting up the trace message when its
trace channel is disabled.  trace_on is a C run-time subroutine and should be
used by application programs, but not by device drivers.

The chanmask parameter is a mask with the bit corresponding to the channel
number set.  It can be formed by the expression "(1 << 31 - "channum")".  User
programs can use only channel number 31, which means that the value of channum
must be "1" for user programs.

Making repeated calls to the trace device driver involves significant overhead,
so call trace_on only once:  either at the start of processing or just before
the first trace point in the program.

If the application trace device driver is not already open, trace_on opens it.

Upon successful completion, trace_on returns 1 if the channel is enabled, or 0
if the channel is disabled.  If the trace_on subroutine fails, a message is
written to the standard error output, and a value of -1 is returned.

FILE

/dev/appltrace

RELATED INFORMATION

In this book:  "trcunix," and "trace."

The trace command in AIX Operating System Commands Reference.

The discussion of trace in AIX Programming Tools and Interfaces.



Processed November 7, 1990      TRACE_ON(3x,L)                                1