InterruptHookTrace()

Attach the pseudo interrupt handler that the instrumented module uses

Synopsis:

#include <sys/neutrino.h>

int InterruptHookTrace( 
   const struct sigevent * (* handler)(int),
   unsigned flags );

Arguments:

handler: A pointer to the handler function.
flags: There are currently no flags that apply; specify 0 for this argument.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The InterruptHookTrace() kernel call attaches handler to the _NTO_HOOK_TRACE synthetic interrupt that the instrumented module uses to notify your program when trace data is available. Before calling this function, the thread must have the PROCMGR_AID_INTERRUPT ability enabled. For more information, see procmgr_ability().

Note: This function requires the instrumented kernel. For more information, see the System Analysis Toolkit (SAT) User's Guide.

You'd use this function if you were writing your own data-capture program and had earlier called TraceEvent() with the _NTO_TRACE_ALLOCBUFFER command to create the kernel's ring of trace buffers.

To detach the interrupt handler, call InterruptDetach(); you can't pass NULL for the handler argument.

The handler argument specifies the function that you want to be called to receive trace events from the kernel. Its prototype is as follows:

const struct sigevent* handler( int info );

You can use some macros that are defined in <sys/trace.h> to extract the data that's included in the info argument:

_TRACE_GET_BUFFNUM(info): Extract the buffer number, which is an index into the kernel's trace buffers. For example, if you allocated four trace buffers, the sequence of buffer numbers would be 0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3, and so on.
_TRACE_GET_BUFFSEQ(info): Extract the buffer sequence number, which indicates where the data in the buffer fits into the progression of data since you started tracing. The buffer sequence numbers start at 1 and increase monotonically. You can use this number to determine whether or not you're keeping up with the trace data.

The handler function runs in the environment of your process. For guidelines on writing this handler, see “Interrupt handler function” in the entry for InterruptAttach().

Blocking states

This call doesn't block.

Returns:

An interrupt function ID, or -1 if an error occurs (errno is set).

Errors:

EAGAIN: All kernel interrupt entries are in use.
EFAULT: A fault occurred when the kernel tried to access the buffers provided.
EINVAL: The handler argument is NULL.
EPERM: The process doesn't have the required permission; see procmgr_ability().
ENOTSUP: The kernel isn't instrumented.

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes