posix_trace_event.3p (6241B)
- '\" et
- .TH POSIX_TRACE_EVENT "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_event,
- posix_trace_eventid_open
- \(em trace functions for instrumenting application code
- (\fBTRACING\fP)
- .SH SYNOPSIS
- .LP
- .nf
- #include <sys/types.h>
- #include <trace.h>
- .P
- void posix_trace_event(trace_event_id_t \fIevent_id\fP,
- const void *restrict \fIdata_ptr\fP, size_t \fIdata_len\fP);
- int posix_trace_eventid_open(const char *restrict \fIevent_name\fP,
- trace_event_id_t *restrict \fIevent_id\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIposix_trace_event\fR()
- function shall record the
- .IR event_id
- and the user data pointed to by
- .IR data_ptr
- in the trace stream into which the calling process is being traced and
- in which
- .IR event_id
- is not filtered out. If the total size of the user trace event data
- represented by
- .IR data_len
- is not greater than the declared maximum size for user trace event
- data, then the
- .IR 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
- .IR truncation-status
- attribute of the trace event recorded is POSIX_TRACE_TRUNCATED_RECORD.
- .P
- 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
- .IR event_id
- is filtered out in the trace stream, the
- \fIposix_trace_event\fR()
- function shall have no effect.
- .P
- The
- \fIposix_trace_eventid_open\fR()
- 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
- .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_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
- traced process, and is returned in the variable pointed to by the
- .IR 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
- .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_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 this same trace stream, and is returned in
- the variable pointed to by the
- .IR 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 (\c
- .IR "Table 2-7" ", " "Trace Option: User Trace Event")
- user trace event shall be returned.
- .TP 10
- .BR 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.
- .P
- .P
- If there is no trace stream created, the
- \fIposix_trace_eventid_open\fR()
- function shall store this information for future trace streams created
- for this process.
- .SH "RETURN VALUE"
- No return value is defined for the
- \fIposix_trace_event\fR()
- function.
- .P
- Upon successful completion, the
- \fIposix_trace_eventid_open\fR()
- function shall return a value of zero. Otherwise, it shall return the
- corresponding error number. The
- \fIposix_trace_eventid_open\fR()
- function stores the trace event type identifier value in the object
- pointed to by
- .IR event_id ,
- if successful.
- .SH ERRORS
- The
- \fIposix_trace_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}.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- None.
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- None.
- .SH "FUTURE DIRECTIONS"
- The
- \fIposix_trace_event\fR()
- and
- \fIposix_trace_eventid_open\fR()
- functions may be removed in a future version.
- .SH "SEE ALSO"
- .IR "Table 2-7" ", " "Trace Option: User Trace Event",
- .IR "\fIexec\fR\^",
- .IR "\fIposix_trace_eventid_equal\fR\^(\|)",
- .IR "\fIposix_trace_start\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<sys_types.h>\fP",
- .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 .