diff options
Diffstat (limited to 'upstream/archlinux/man3p/posix_trace_eventid_equal.3p')
| -rw-r--r-- | upstream/archlinux/man3p/posix_trace_eventid_equal.3p | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/posix_trace_eventid_equal.3p b/upstream/archlinux/man3p/posix_trace_eventid_equal.3p new file mode 100644 index 00000000..c4bf5e41 --- /dev/null +++ b/upstream/archlinux/man3p/posix_trace_eventid_equal.3p @@ -0,0 +1,227 @@ +'\" 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 . |