The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

#### NAME

> posix_trace_event, posix_trace_eventid_open - trace functions for instrumenting application code (TRACING)

#### SYNOPSIS

> ``[TRC] #include <sys/types.h>
> #include <trace.h>
> void posix_trace_event(trace_event_id_t` event_id`,
> const void *restrict`data_ptr`, size_t` data_len`);
> int posix_trace_eventid_open(const char *restrict` event_name`,
> trace_event_id_t *restrict` event_id`);``
> `
> `

#### DESCRIPTION

> The posix_trace_event() function shall record the event_id and the user data pointed to by data_ptr in the trace stream into which the calling process is being traced and in which event_id is not filtered out. If the total size of the user trace event data represented by data_len is not greater than the declared maximum size for user trace event data, then the truncation-status attribute of the trace event recorded is POSIX_TRACE_NOT_TRUNCATED. Otherwise, the user trace event data is truncated to this declared maximum size and the truncation-status attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD.

> If there is no trace stream created for the process or if the created trace stream is not running, or if the trace event specified by event_id is filtered out in the trace stream, the posix_trace_event() function shall have no effect.

> The posix_trace_eventid_open() function shall associate 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 argument event_name. It shall have a maximum of {TRACE_EVENT_NAME_MAX} characters (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 {TRACE_USER_EVENT_MAX}, which has the minimum value {POSIX_TRACE_USER_EVENT_MAX}.

> If the Trace Inherit option is not supported, the posix_trace_eventid_open() function shall associate the user trace event name pointed to by the event_name argument with a trace event type identifier that is unique for the traced process, and is returned in the variable pointed to by the event_id argument. If the user trace event name has already been mapped for the traced process, then the previously assigned trace event type identifier shall be returned. If the per-process user trace event name limit represented by {TRACE_USER_EVENT_MAX} has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see Trace Option: User Trace Event ) user trace event shall be returned.

> [TRI] If the Trace Inherit option is supported, the posix_trace_eventid_open() function shall associate the user trace event name pointed to by the event_name argument with a trace event type identifier that is unique for all the processes being traced in this same trace stream, and is returned in the variable pointed to by the event_id argument. If the user trace event name has already been mapped for the traced processes, then the previously assigned trace event type identifier shall be returned. If the per-process user trace event name limit represented by {TRACE_USER_EVENT_MAX} has been reached, the pre-defined POSIX_TRACE_UNNAMED_USEREVENT ( Trace Option: User Trace Event ) user trace event shall be 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() function shall store this information for future trace streams created for this process.

#### RETURN VALUE

> No return value is defined for the posix_trace_event() function.

> Upon successful completion, the posix_trace_eventid_open() function shall return a value of zero. Otherwise, it shall return the corresponding error number. The posix_trace_eventid_open() function stores the trace event type identifier value in the object pointed to by event_id, if successful.

#### ERRORS

> The posix_trace_eventid_open() function shall fail if:

> [ENAMETOOLONG]
>   The size of the name pointed to by the event_name argument was longer than the implementation-defined value {TRACE_EVENT_NAME_MAX}.

The following sections are informative.

#### EXAMPLES

> None.

#### APPLICATION USAGE

> None.

#### RATIONALE

> None.

#### FUTURE DIRECTIONS

> None.

#### SEE ALSO

> Trace Option: User Trace Event, posix_trace_start(), posix_trace_trid_eventid_open(), the Base Definitions volume of IEEE Std 1003.1-2001, <sys/types.h>, <trace.h>

#### CHANGE HISTORY

> First released in Issue 6. Derived from IEEE Std 1003.1q-2000.

> IEEE PASC Interpretation 1003.1 #123 is applied.

> IEEE PASC Interpretation 1003.1 #127 is applied, correcting some editorial errors in the names of the posix_trace_eventid_open() function and the event_id argument.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]