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 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 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 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 above procedure, 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 created, the posix_trace_eventid_open subroutine stores this information for future trace streams created for this process.

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:

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 AIX® Version 7.1 Files Reference.