qnx_trace_read()

read events from a trace buffer

Synopsis:

#include <sys/trace.h>
int qnx_trace_read( pid_t proc_pid,
                    size_t size,
                    char *buffer,
                    int *overruns );

Description:

The qnx_trace_read() function reads up to size bytes of events (rounded down to last complete event that fits) from the trace buffer into buffer.

Each trace event consists of a struct _trace_event header, followed by the variable length data for that event. The length member indicates the total number of bytes of the event, including the header. The events are concatenated, and the last event in the buffer is a null event with a length of zero.

If the _TRACE_CLEAR_BUFF flag was specified to qnx_trace_open(), events are cleared from the buffer after they're read.

The current value of the overrun counter is always copied into the location pointed to by overruns. If the _TRACE_CLEAR_OVERRUNS flag was specified to qnx_trace_open(), the overrun counter is cleared. (Overruns occur when the trace buffer is full, and the new events overwrite previous events).

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:

EINVAL: The qnx_trace_open() function hasn't been called or your receive buffer is too small to receive an EOK event.
ENOSYS: The process manager doesn't support trace calls.
EAGAIN: Resource is unavailable, try again. This usually happens when trace events are occurring too fast.
EMORE: There are more events in buffer.
ESRCH: The proc_pid is invalid.

With EAGAIN, EMORE and EOK, the buffer should be scanned for returned data, as the error could have occurred in the middle of filling your buffer.

Examples:

/*
 * Display the trace log
 */

#include <stdio.h>
#include <stdlib.h>
#include <errno.h>
#include <sys/trace.h>
#include <sys/tracecod.h>

void main()
  {
    struct _trace_event *t;
    char buff[1000];
    int ret;

    if( qnx_trace_open( 0, 0 ) == -1 ) {
      fprintf(stderr, "Can't access trace buffer\n");
      exit(EXIT_FAILURE);
    }

    do {
      ret = qnx_trace_read( 0, sizeof( buff ), buff, NULL );

      if( ret == -1     &&
        errno != EMORE    &&
        errno != EINVAL &&
        errno != EAGAIN )
              break;

      for( t = (struct _trace_event *)buff;
           t->length;
           t = (struct _trace_event *)
               ( (char *)t + t->length ) ) {
        printf( "%d %12.12s %08lx\n", t->severity,
           ctime( &t->seconds )+4, t->code );
      }
    } while( ret == -1 &&
        ( errno == EMORE || errno == EAGAIN ) );

    qnx_trace_close( 0 );

    if( ret == -1 ) {
      fprintf( stderr,
          "Error while reading trace buffer\n" );
      exit( EXIT_FAILURE );
    }

    exit( EXIT_SUCCESS );
  }

Classification:

QNX

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