qnx_trace_open()

open a channel to a trace buffer

Synopsis:

#include <sys/trace.h>
int qnx_trace_open( pid_t proc_pid,
                    unsigned flags );

The qnx_trace_open() function opens a channel to a trace buffer, and must be called before qnx_trace_read() can be used to read events from the trace buffer. Only one process at a time is permitted to have a node's trace channel open.

The qnx_trace_open() and qnx_trace_read() functions are only used to read trace information. Programs wishing to log trace events must do so by calling the Trace() family of functions.

The flags are defined as:

_TRACE_CLEAR_BUFF: Clear the events from the buffer as they are read.
_TRACE_CLEAR_OVERRUNS: Clear the overrun count on every read.

The qnx_trace_open() function sets the read pointer to the oldest event in the message queue. If you're reading without clearing, you may call this function to re-start the read without closing first.

If proc_pid is zero or PROC_PID, the trace buffer on the current node is accessed. To access a trace buffer on another node you must establish a virtual circuit to the process manager on that node and pass the vid as proc_pid.

Returns:

0: Success
-1: An error occurred. errno is set to indicate the error.

Errors:

EBUSY: Someone else is already accessing the trace buffer.
ENOSYS: The process manager doesn't support trace calls.
EPERM: The calling process doesn't have sufficient privilege to open a trace buffer.
ESRCH: The proc_pid is invalid.

Examples:

See qnx_trace_read().

Classification:

QNX

Safety:
Interrupt handler	No
Signal handler	Yes, but modifies errno
Thread	Yes