posix_trace_trid_eventid_open Subroutine

Edit online

Purpose

Associates a trace event type identifier to a user trace event name.

Library

Posix Trace Library (libposixtrace.a)

Syntax

#include <trace.h>

int posix_trace_trid_eventid_open(trid, event_name, event)
trace_id_t trid;
const char *restrict event_name;
trace_event_id_t *restrict event;

Description

The posix_trace_trid_eventid_open subroutine associates a user trace event name with a trace event type identifier for a given trace stream. The trace stream is identified by the trid parameter, and it need to be an active trace stream. The event_name parameter points to the trace event name that is a string. It must have a maximum number of the characters that is defined in the TRACE_EVENT_NAME_MAX variable, (which has the minimum value _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 by the TRACE_USER_EVENT_MAX that has the minimum value of _POSIX_TRACE_USER_EVENT_MAX.

The posix_trace_trid_eventid_open subroutine associates the user trace event name with a trace event type identifier for a given trace stream. The trace event type identifier is unique for all of the processes being traced in the trace stream. The trid parameter defines the trace stream. The trace event type identifier is returned in the variable pointed to by the event parameter. If the user trace event name is already 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 is reached, the POSIX_TRACE_UNNAMED_USEREVENT user trace event previously defined is returned.

Parameters

Item Description
trid Specifies the trace stream identifier.
event_name Specifies the trace event name.
event Specifies the trace event identifiers.

Return Values

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

If successful, the posix_trace_trid_eventid_open subroutine stores the value of the trace event type identifier in the object pointed to by the event parameter.

Errors

The posix_trace_trid_eventid_open subroutine fails if one of the following value returns:
Item Description
EINVAL The trid parameter is not a valid trace stream identifier. The trace event type identifier event is not associated with any name.
ENAMETOOLONG The size of the name pointed to by the event_name parameter is longer than the TRACE_EVENT_NAME_MAX.

File

The trace.h file in Files Reference.