posix_trace_eventid_open Subroutine

Purpose

Trace subroutine for instrumenting application code.

Library

Posix Trace Library (libposixtrace.a)

Syntax

#include <sys/type.h>
#include <trace.h>

int posix_trace_eventid_open(event_name, event_id)
const char *restrict event_name;
trace_event_id_t *restrict event_id;

Description

The posix_trace_eventid_open subroutine associates a user trace event name with a trace event type identifier for the calling process. The trace event name is the string pointed to by the event_name parameter. It can have a maximum number of characters that are defined in the TRACE_EVENT_NAME_MAX (which has the minimum value of _POSIX_TRACE_EVENT_NAME_MAX). The number of user trace event type identifiers that can be defined for any given process is limited by the maximum value that is defined in the TRACE_USER_EVENT_MAX, which has the minimum value _POSIX_TRACE_USER_EVENT_MAX.

The posix_trace_eventid_open subroutine associates the user trace event name pointed to by the event_name parameter with a trace event type identifier that is unique for all of the processes being traced in this same trace stream, and is returned in the variable pointed to by the event_id parameter. If the user trace event name has already been mapped for the traced processes, the previously assigned trace event type identifier is returned. If the per-process user trace event name limit that is represented by the TRACE_USER_EVENT_MAX value has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT user trace event is returned.

Note: The procedure before this, together with the fact that multiple processes can only be traced into the same trace stream by inheritance, ensure that all the processes that are traced into a trace stream have the same mapping of trace event names to trace event type identifiers.

If there is no trace stream that is created, the posix_trace_eventid_open subroutine stores this information for future trace streams created for this process.

Parameter

Table 1. Parameter
Item	Description
`event_name`	Specifies the trace event name.
`event_id`	Specifies the trace event identifier.

Return Values

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

If successful, the posix_trace_eventid_open subroutine stores the trace event type identifier value in the object pointed to by event_id.

Errors

The posix_trace_eventid_open subroutine fails if the following error returns:

Table 2. Errors
Item	Description
`ENAMETOOLONG`	The size of the name pointed to by the `event_name` parameter is longer than the value defined by `TRACE_EVENT_NAME_MAX`.

Files

The trace.h and types.h files in Files Reference.