posix_trace_eventid_equal.3p (7072B)
- '\" et
- .TH POSIX_TRACE_EVENTID_EQUAL "3P" 2017 "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\(hy2017,
- .IR "\fB<trace.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- 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.opengroup.org/unix/online.html .
- .PP
- 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 .