Trace functions()

log timestamped data into an internal buffer

Synopsis:

#include <sys/trace.h>
#include <sys/tracecod.h>
int Trace0  (unsigned long code, int severity );
int Trace0b (unsigned long code, int severity,
             int nbytes, void *data );
int Trace1  (unsigned long code, int severity, 
             int arg1 );
int Trace1b (unsigned long code, int severity, 
             int arg1, int nbytes, void *data );
int Trace2  (unsigned long code, int severity, 
             int arg1, int arg2 );
int Trace2b (unsigned long code, int severity,
             int arg1, int arg2, int nbytes, 
             void *data );
int Trace3  (unsigned long code, int severity,
             int arg1, int arg2, int arg3 );
int Trace3b (unsigned long code, int severity,
             int arg1, int arg2, int arg3,
             int nbytes, void *data );
int Trace4  (unsigned long code, int severity,
             int arg1, int arg2, int arg3,
             int arg4 );
int Trace4b (unsigned long code, int severity,
             int arg1, int arg2, int arg3,
             int arg4, int nbytes, void *data );
int Trace5  (unsigned long code, int severity,
             int arg1, int arg2, int arg3,
             int arg4, int arg5 );
int Trace5b (unsigned long code, int severity,
             int arg1, int arg2, int arg3,
             int arg4, int arg5, int nbytes,
             void *data );
int Trace6  (unsigned long code, int severity,
             int arg1, int arg2, int arg3,
             int arg4, int arg5, int arg6 );
int Trace6b (unsigned long code, int severity,
             int arg1, int arg2, int arg3,
             int arg4, int arg5, int arg6,
             int nbytes, void *data );

The Trace... functions log timestamped data into an internal operating system buffer. There's one trace buffer per machine, which is allocated by the process manager at boot time (-T option to Proc32). When the buffer is full, the oldest events are removed and an overrun counter is incremented. Since all processes on a node share a common trace buffer, only abnormal events should be traced.

Each time a Trace... function is called, an event is logged into the trace buffer. An event consists of a struct _trace_event header followed by the caller's data (as specified to the particular Trace... function that was used).

The data to be logged is contained in the int arguments (for example, arg1, arg2...) and/or in a data buffer containing nbytes of data. The total size of an event including the struct _trace_event header cannot exceed 511 bytes. For an example of reading trace data, see qnx_trace_read().

The Trace... functions can be called at any time, (that is, from an interrupt handler or from a normal process).

The code parameter signifies a type of event (typically associated with a resource manager). Codes are composed of a 32-bit number where the upper 20 bits are a type, and the lower 12 bits are a sub-code for that type.

Values for code are assigned by Technical Support at QNX Software Systems Ltd. At least the following type codes are defined in <sys/tracecod.h>:

_TRACE_PROC

Event from the process manager

_TRACE_DEV

Event from the device manager

_TRACE_FSYS

Event from the filesystem manager

_TRACE_NET

Event from the network manager

_TRACE_TEMPORARY

This code can be used until you obtain your own type code by contacting QNX Software Systems Ltd.

You should never ship any product that uses the _TRACE_TEMPORARY type code.

The severity parameter associates an importance factor to the trace event. The severity level can be set to one of the following, as defined in <sys/trace.h>:

_TRACE_CRITICAL: Major fault: this should never happen
_TRACE_SEVERE: Hardware failure (major)
_TRACE_TRANSIENT: Could possibly happen (for example, bad blocks)
_TRACE_COMMON: Common errors
_TRACE_EXPECTED: Expected errors (for example, CRC error)
_TRACE_TESTING: Used only for debugging. Since this is the lowest severity level, events at this level may not be logged into the trace buffer unless the default operating system severity criteria is changed (see qnx_trace_severity() ).

Returns:

The Trace... functions return zero if the data was saved. If the system severity logging level is lower than the severity of this event, or if the trace buffer isn't allocated, -1 is returned.

The errno variable isn't modified by these functions.

Examples:

 /*
 * Save a temporary trace event with sub-code 10
 */
#include <stdio.h>
#include <sys/trace.h>
#include <sys/tracecod.h>

void main()
  {
    Trace3(_TRACE_TEMPORARY|10, _TRACE_TESTING, 1, 2, 3);
  }

Classification:

QNX

Safety:
Interrupt handler	Yes
Signal handler	Yes
Thread	Yes

Caveats:

In order to use the Trace... functions, your program must be compiled at privity level 1 and run as root. See the -T option for the cc command, or the OPTION PRIVILEGE linker directive.

This limitation doesn't exist under Neutrino.