mirror of https://github.com/mkerrisk/man-pages
167 lines
6.5 KiB
Plaintext
167 lines
6.5 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "POSIX_TRACE_EVENTID_EQUAL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" posix_trace_eventid_equal
|
|
.SH NAME
|
|
posix_trace_eventid_equal, posix_trace_eventid_get_name, posix_trace_trid_eventid_open
|
|
\- manipulate the trace event
|
|
type identifier (\fBTRACING\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <trace.h>
|
|
.br
|
|
.sp
|
|
int posix_trace_eventid_equal(trace_id_t\fP \fItrid\fP\fB, trace_event_id_t\fP
|
|
\fIevent1\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ trace_event_id_t\fP \fIevent2\fP\fB);
|
|
.br
|
|
int posix_trace_eventid_get_name(trace_id_t\fP \fItrid\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ trace_event_id_t\fP \fIevent\fP\fB, char *\fP\fIevent_name\fP\fB);
|
|
.br
|
|
\fP
|
|
.LP
|
|
\fBint posix_trace_trid_eventid_open(trace_id_t\fP \fItrid\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ const char *restrict\fP \fIevent_name\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ trace_event_id_t *restrict\fP \fIevent\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIposix_trace_eventid_equal\fP() function shall compare the trace
|
|
event type identifiers \fIevent1\fP and \fIevent2\fP
|
|
from the same trace stream or the same trace log identified by the
|
|
\fItrid\fP argument. If the trace event type identifiers
|
|
\fIevent1\fP and \fIevent2\fP are from different trace streams, the
|
|
return value shall be unspecified.
|
|
.LP
|
|
The \fIposix_trace_eventid_get_name\fP() function shall return, in
|
|
the argument pointed to by \fIevent_name\fP, the trace
|
|
event name associated with the trace event type identifier identified
|
|
by the argument \fIevent\fP, for the trace stream or for the
|
|
trace log identified by the \fItrid\fP 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.
|
|
.LP
|
|
The \fIposix_trace_trid_eventid_open\fP() 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 \fItrid\fP
|
|
argument, and it shall be an active trace stream. The trace
|
|
event name is the string pointed to by the argument \fIevent_name\fP.
|
|
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}.
|
|
.LP
|
|
If the Trace Inherit option is not supported, the \fIposix_trace_trid_eventid_open\fP()
|
|
function shall associate the user trace
|
|
event name pointed to by the \fIevent_name\fP argument with a trace
|
|
event type identifier that is unique for the process being
|
|
traced in the trace stream identified by the \fItrid\fP argument,
|
|
and is returned in the variable pointed to by the \fIevent\fP
|
|
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 \fITrace
|
|
Option: User Trace
|
|
Event\fP ) user trace event shall be returned.
|
|
.LP
|
|
If the Trace Inherit option is supported, the \fIposix_trace_trid_eventid_open\fP()
|
|
function shall associate the user
|
|
trace event name pointed to by the \fIevent_name\fP argument with
|
|
a trace event type identifier that is unique for all the
|
|
processes being traced in the trace stream identified by the \fItrid\fP
|
|
argument, and is returned in the variable pointed to by
|
|
the \fIevent\fP 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 \fITrace Option: User Trace Event\fP ) user trace event shall
|
|
be returned.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, the \fIposix_trace_eventid_get_name\fP()
|
|
and
|
|
\fIposix_trace_trid_eventid_open\fP() functions shall return a
|
|
value of zero. Otherwise, they shall return the corresponding error
|
|
number.
|
|
.LP
|
|
The \fIposix_trace_eventid_equal\fP() function shall return a non-zero
|
|
value if \fIevent1\fP and \fIevent2\fP are equal;
|
|
otherwise, a value of zero shall be returned. No errors are defined.
|
|
If either \fIevent1\fP or \fIevent2\fP are not valid trace
|
|
event type identifiers for the trace stream specified by \fItrid\fP
|
|
or if the \fItrid\fP is invalid, the behavior shall be
|
|
unspecified.
|
|
.LP
|
|
The \fIposix_trace_eventid_get_name\fP() function stores the trace
|
|
event name value in the object pointed to by
|
|
\fIevent_name\fP, if successful.
|
|
.LP
|
|
The \fIposix_trace_trid_eventid_open\fP() function stores the trace
|
|
event type identifier value in the object pointed to by
|
|
\fIevent\fP, if successful.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIposix_trace_eventid_get_name\fP() and \fIposix_trace_trid_eventid_open\fP()
|
|
functions shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fItrid\fP argument was not a valid trace stream identifier.
|
|
.sp
|
|
.LP
|
|
The \fIposix_trace_trid_eventid_open\fP() function shall fail if:
|
|
.TP 7
|
|
.B ENAMETOOLONG
|
|
.sp
|
|
The size of the name pointed to by the \fIevent_name\fP argument was
|
|
longer than the implementation-defined value
|
|
{TRACE_EVENT_NAME_MAX}.
|
|
.sp
|
|
.LP
|
|
The \fIposix_trace_eventid_get_name\fP() function shall fail if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The trace event type identifier \fIevent\fP was not associated with
|
|
any name.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fITrace Option: User Trace Event\fP , \fIposix_trace_event\fP() ,
|
|
\fIposix_trace_getnext_event\fP() , the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<trace.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|