NAME
irTrace, irQTrace, irTraceP, irQTraceP, irTRACEPROC_CHK,
irTRACECHAN_CHK, irTrace_Put, irSetTraceArea, irSetTraceQ-
key, irSetTraceChan, irSetTraceLevel, irSetTraceLogMode,
irSetTraceDateMode, irSetTraceLboltMode - append data to the
trace log
SYNOPSIS
#include <irapi.h>
void irTrace (int channel, unsigned long level, unsigned
long area, const char *fmt, /*varargs*/);
void irQTrace (int channel, unsigned long level, unsigned
long area, const char *str);
void irTraceP (int channel, unsigned long level, unsigned
long area, const char *fmt, /*varargs*/);
void irQTraceP (int channel, unsigned long level, unsigned
long area, const char *str);
int irTRACECHAN_CHK (int channel, unsigned long level,
unsigned long area);
int irTRACEPROC_CHK (int channel, unsigned long level,
unsigned long area);
void irTrace_Put (const char *str);
void irSetTraceChan (int channel, int flag);
void irSetTraceQkey (ir_key_t qkey, int flag);
void irSetTraceArea (unsigned long area, int flag);
void irSetTraceLevel (unsigned long level, int flag);
void irSetTraceLogMode (int flag);
void irSetTraceDateMode (int flag);
void irSetTraceLboltMode (int flag);
DESCRIPTION
irTrace formats and logs data into the trace shared memory
buffer or to the trace log if tracing is on for the speci-
fied channel at the indicated level for area. Any level of
tracing is allowed.
irTraceP formats and logs data into the trace shared memory
buffer or to the trace log if tracing is on for the
indicated level for area and for the calling process, or if
the channel is valid and tracing is on for that channel.
Any level of tracing is allowed. If channel is -1, the
trace message does not display the channel number.
irQTrace and irQTraceP are "quick" versions of irTrace and
irTraceP, respectively. irQTrace and irQTraceP are macros
that perform all the necessary checks, and then only call a
trace subroutine if necessary. However, irQTrace and
irQTraceP do not accept variable arguments.
The irTRACECHAN_CHK macro returns non-zero if channel-level
tracing is on for the given channel, level, and area.
The irTRACEPROC_CHK macro returns non-zero if process-level
tracing is turned on for this process' given channel, level,
and area.
irTrace_Put writes the given str into the trace shared
memory buffer or to the trace log unconditionally. It is
recommended that this function be used in conjunction with
the irTRACECHAN_CHK and irTRACEPROC_CHK macros.
By default, trace messages are logged to the trace shared
memory buffer. To direct the trace messages to the trace
log file, call irSetTraceLogMode with a argument of IRD_ON.
To direct the trace messages to the trace shared memory
buffer, call irSetTraceLogMode with a argument of IRD_OFF.
By default, trace messages are not timestamped nor
lboltstampped when they are placed in the trace shared
memory buffer. To turn on the timestamping of every trace
message when it is placed in the trace buffer, call irSet-
TraceDateMode with a argument of IRD_ON. To turn off the
timestamping of every trace message, call irSetTraceDateMode
with a argument of IRD_OFF. To turn on the lboltstamping of
every trace message when it is placed in the trace buffer,
call irSetTraceLboltMode with a argument of IRD_ON. To turn
off the lboltstamping of every trace message, call irSetTra-
ceLboltMode with a argument of IRD_OFF.
fmt is a printf(3s) style formatting string and varargs are
the arguments required to format the string. All trace mes-
sages logged with irTrace are logged with the TRACE001 mes-
sage. By default, TRACE001 is assigned to the trace logger
destination. The TRACE001 log message has the following
format:
TRACE001 -- CH %3d<<chan,D>> (TRACE_GEN) %s<<message,S>>
Here, %3d<<chan>> is the channel argument and
%s<<message,S>> is fmt formatted with varargs.
Trace messages are logged only when some process either via
trace(1VIS) or irSetTrace<Type> send tracing on messages
matching the arguments set to irTrace.
A process must be registered with irRegister(3IRAPI) before
tracing for that process may begin.
irSetTraceChan activates or deactivates trace messages for
chan as indicated by flag. flag may be either IRD_ON or
IRD_OFF.
irSetTraceArea activates or deactivates trace messages for
area as indicated by flag. flag may be either IRD_ON or
IRD_OFF.
irSetTraceLevel activates or deactivates trace messages for
level as indicated by flag. flag may be either IRD_ON or
IRD_OFF.
irSetTraceQkey activates or deactivates trace messages for
qkey as indicated by flag. flag may be either IRD_ON or
IRD_OFF.
areas and levels are bit maps used to allow trace(1VIS) to
be more selective in terms of trace output. This means the
higher the level, the greater the level of detail on trace
output. Level 32 messages include the greatest level of
detail, and level 1, the least. Trace levels are defined by
the IRD_TRACE_LEVEL_1 through IRD_TRACE_LEVEL_16 for user
defined levels, these levels occupy bits 0 through 15 in the
level bit mask. IRAPI applications may use these levels and
attach whatever meaning to these levels that suits them.
trace(1VIS) supports tracing on these user defined levels.
Trace levels 17 through 32 are reserved for internal IRAPI
library functions and VIS processes. It is not recommended
that user applications generate trace messages in the
reserved levels. However, applications may use
irSetTraceLevel to enable tracing on these levels.
Trace areas are defined by the IRD_TRACE_AREA_1 through
IRD_TRACE_AREA_16 for user defined areas, these areas occupy
bits 0 through 15 in the area bit mask. IRAPI applications
may use these areas and attach whatever meaning suits them
to these areas. trace(1VIS) supports tracing on these user
defined areas. Trace areas 17 through 32 are reserved for
internal IRAPI library functions and VIS processes. Defines
symbols for these areas are found in IrDEFINES(4IRAPI) as
IRD_TRACE_AREA_<area>, where <area> is a two letter mnemonic
for the particular area. It is not recommended that user
applications generate trace messages in the reserved areas.
However, applications may use irSetTraceArea to enable trac-
ing on these areas.
Tracing may be done on these areas and levels through the
trace(1VIS) command.
EVENT
No event results from the call to irTrace.
RETURN VALUE
none
ERROR
none
NOTE
Never call irTrace nor irQTrace with an invalid channel
number, otherwise the trace message will always be displayed
regardless of whether the process or channel is being
traced.
SEE ALSO
trace(1VIS), IrDEFINES(4IRAPI).
VERSION
This is version 11/25/02 of this man page.