'\" et

.TH POSIX_TRACE_EVENTID_EQUAL "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"

.SH PROLOG

This manual page is part of the POSIX Programmer's Manual.

The Linux implementation of this interface may differ (consult

the corresponding Linux manual page for details of Linux behavior),

or the interface may not be implemented on Linux.

.SH NAME

posix_trace_eventid_equal,

posix_trace_eventid_get_name,

posix_trace_trid_eventid_open

\(em manipulate the trace event type identifier

(\fBTRACING\fP)

.SH SYNOPSIS

.LP

.nf

#include <trace.h>

.P

int posix_trace_eventid_equal(trace_id_t \fItrid\fP, trace_event_id_t \fIevent1\fP,

    trace_event_id_t \fIevent2\fP);

int posix_trace_eventid_get_name(trace_id_t \fItrid\fP,

    trace_event_id_t \fIevent\fP, char *\fIevent_name\fP);

int posix_trace_trid_eventid_open(trace_id_t \fItrid\fP,

    const char *restrict \fIevent_name\fP,

    trace_event_id_t *restrict \fIevent\fP);

.fi

.SH DESCRIPTION

The

\fIposix_trace_eventid_equal\fR()

function shall compare the trace event type identifiers

.IR event1

and

.IR event2

from the same trace stream or the same trace log identified by the

.IR trid

argument. If the trace event type identifiers

.IR event1

and

.IR event2

are from different trace streams, the return value shall be

unspecified.

.P

The

\fIposix_trace_eventid_get_name\fR()

function shall return, in the argument pointed to by

.IR event_name ,

the trace event name associated with the trace event type identifier

identified by the argument

.IR event ,

for the trace stream or for the trace log identified by the

.IR trid

argument. The name of the trace event shall have a maximum of

{TRACE_EVENT_NAME_MAX}

characters (which has the minimum value

{_POSIX_TRACE_EVENT_NAME_MAX}).

Successive calls to this function with the same trace event type

identifier and the same trace stream identifier shall return the same

event name.

.P

The

\fIposix_trace_trid_eventid_open\fR()

function shall associate a user trace event name with a trace

event type identifier for a given trace stream. The trace stream is

identified by the

.IR trid

argument, and it shall be an active trace stream. The trace event name

is the string pointed to by the argument

.IR 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}.

.P

If the Trace Inherit option is not supported, the

\fIposix_trace_trid_eventid_open\fR()

function shall associate the user trace event name pointed to by the

.IR event_name

argument with a trace event type identifier that is unique for the

process being traced in the trace stream identified by the

.IR trid

argument, and is returned in the variable pointed to by the

.IR event

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

.IR "Table 2-7" ", " "Trace Option: User Trace Event")

user trace event shall be returned.

.P

If the Trace Inherit option is supported, the

\fIposix_trace_trid_eventid_open\fR()

function shall associate the user trace event name pointed to by the

.IR event_name

argument with a trace event type identifier that is unique for all the

processes being traced in the trace stream identified by the

.IR trid

argument, and is returned in the variable pointed to by the

.IR event

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 (see

.IR "Table 2-7" ", " "Trace Option: User Trace Event")

user trace event shall be returned.

.SH "RETURN VALUE"

Upon successful completion, the

\fIposix_trace_eventid_get_name\fR()

and

\fIposix_trace_trid_eventid_open\fR()

functions shall return a value of zero. Otherwise, they shall return

the corresponding error number.

.P

The

\fIposix_trace_eventid_equal\fR()

function shall return a non-zero value if

.IR event1

and

.IR event2

are equal; otherwise, a value of zero shall be returned. No errors are

defined. If either

.IR event1

or

.IR event2

are not valid trace event type identifiers for the trace stream

specified by

.IR trid

or if the

.IR trid

is invalid, the behavior shall be unspecified.

.P

The

\fIposix_trace_eventid_get_name\fR()

function stores the trace event name value in the object pointed to by

.IR event_name ,

if successful.

.P

The

\fIposix_trace_trid_eventid_open\fR()

function stores the trace event type identifier value in the object

pointed to by

.IR event ,

if successful.

.SH ERRORS

The

\fIposix_trace_eventid_get_name\fR()

and

\fIposix_trace_trid_eventid_open\fR()

functions shall fail if:

.TP

.BR EINVAL

The

.IR trid

argument was not a valid trace stream identifier.

.P

The

\fIposix_trace_trid_eventid_open\fR()

function shall fail if:

.TP

.BR ENAMETOOLONG

.br

The size of the name pointed to by the

.IR event_name

argument was longer than the implementation-defined value

{TRACE_EVENT_NAME_MAX}.

.P

The

\fIposix_trace_eventid_get_name\fR()

function shall fail if:

.TP

.BR EINVAL

The trace event type identifier

.IR event

was not associated with any name.

.LP

.IR "The following sections are informative."

.SH EXAMPLES

None.

.SH "APPLICATION USAGE"

None.

.SH RATIONALE

None.

.SH "FUTURE DIRECTIONS"

The

\fIposix_trace_eventid_equal\fR(),

\fIposix_trace_eventid_get_name\fR(),

and

\fIposix_trace_trid_eventid_open\fR()

functions may be removed in a future version.

.SH "SEE ALSO"

.ad l

.IR "Table 2-7" ", " "Trace Option: User Trace Event",

.IR "\fIexec\fR\^",

.IR "\fIposix_trace_event\fR\^(\|)",

.IR "\fIposix_trace_getnext_event\fR\^(\|)"

.ad b

.P

The Base Definitions volume of POSIX.1\(hy2008,

.IR "\fB<trace.h>\fP"

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 7, Copyright (C) 2013 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group.

(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the

event of any discrepancy between this version and the original IEEE and

The Open Group Standard, the original IEEE and The Open Group Standard

is the referee document. The original Standard can be obtained online at

http://www.unix.org/online.html .

Any typographical or formatting errors that appear

in this page are most likely

to have been introduced during the conversion of the source files to

man page format. To report such errors, see

https://www.kernel.org/doc/man-pages/reporting_bugs.html .