posix_trace_open Subroutine

Purpose

Opens a trace log.

Library

Posix Trace Library (libposixtrace.a)

Syntax

#include <trace.h>

int posix_trace_open (file_desc, trid)
int file_desc;
trace_id_t *trid;

Description

The posix_trace_open subroutine allocates the necessary resources and establish the connection between a trace log identified by the file_desc parameter and a trace stream identifier identified by the object pointed to by the trid parameter. The file_desc parameter must be a valid open file descriptor that corresponds to a trace log. The file_desc parameter must be open for reading. The current trace event time stamp is set to the time stamp of the oldest trace event recorded in the trace log identified by the trid parameter. The current trace event time stamp specifies the time stamp of the trace event that will be read by the next call to the posix_trace_getnext_event.

The posix_trace_open subroutine returns a trace stream identifier in the variable pointed to by the trid parameter, which might only be used by the following subroutines:
  • The posix_trace_close subroutine
  • The posix_trace_eventid_equal subroutine
  • The posix_trace_eventid_get_name subroutine
  • The posix_trace_eventtypelist_getnext_id subroutine
  • The posix_trace_eventtypelist_rewind subroutine
  • The posix_trace_get_attr subroutine
  • The posix_trace_get_status subroutine
  • The posix_trace_getnext_event subroutine
  • The posix_trace_rewind subroutine

Note that the operations used by a trace controller process, such as the posix_trace_start, posix_trace_stop, or the posix_trace_shutdown subroutine, cannot be invoked using the trace stream identifier returned by the posix_trace_open subroutine.

Parameters

Item Description
file_desc Specifies the open file descriptor of the trace log.
trid Specifies the trace stream identifier.

Return Values

On successful completion, this subroutine returns a value of zero. Otherwise, it returns the corresponding error number.

If successful, the posix_trace_open subroutine stores the trace stream identifier value in the object pointed to by the trid parameter.

Errors

The posix_trace_open subroutine fails if the following errors return:
Item Description
EBADF The file_desc parameter is not a valid file descriptor open for reading.
EINVAL The object pointed to by file_desc does not correspond to a valid trace log.

Files

The trace.h file in the Files Reference.