diff options
Diffstat (limited to 'man3p/posix_trace_event.3p')
-rw-r--r-- | man3p/posix_trace_event.3p | 138 |
1 files changed, 138 insertions, 0 deletions
diff --git a/man3p/posix_trace_event.3p b/man3p/posix_trace_event.3p new file mode 100644 index 000000000..f495da08a --- /dev/null +++ b/man3p/posix_trace_event.3p @@ -0,0 +1,138 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "POSIX_TRACE_EVENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" posix_trace_event +.SH NAME +posix_trace_event, posix_trace_eventid_open \- trace functions for +instrumenting application code +(\fBTRACING\fP) +.SH SYNOPSIS +.LP +\fB#include <sys/types.h> +.br +#include <trace.h> +.br +.sp +void posix_trace_event(trace_event_id_t\fP \fIevent_id\fP\fB, +.br +\ \ \ \ \ \ const void *restrict\fP\fIdata_ptr\fP\fB, size_t\fP \fIdata_len\fP\fB); +.br +int posix_trace_eventid_open(const char *restrict\fP \fIevent_name\fP\fB, +.br +\ \ \ \ \ \ trace_event_id_t *restrict\fP \fIevent_id\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIposix_trace_event\fP() function shall record the \fIevent_id\fP +and the user data pointed to by \fIdata_ptr\fP in the +trace stream into which the calling process is being traced and in +which \fIevent_id\fP is not filtered out. If the total size of +the user trace event data represented by \fIdata_len\fP is not greater +than the declared maximum size for user trace event data, +then the \fItruncation-status\fP 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 \fItruncation-status\fP +attribute of the trace event recorded is +POSIX_TRACE_TRUNCATED_RECORD. +.LP +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 \fIevent_id\fP is filtered out in the trace stream, the +\fIposix_trace_event\fP() function shall have no effect. +.LP +The \fIposix_trace_eventid_open\fP() 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 \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_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 traced process, +and is returned in the variable pointed to by the \fIevent_id\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_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 this same trace stream, and is returned in the variable pointed +to by the \fIevent_id\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 ( \fITrace Option: User Trace Event\fP +) user trace event +shall be returned. +.TP 7 +\fBNote:\fP +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. +.sp +.LP +If there is no trace stream created, the \fIposix_trace_eventid_open\fP() +function shall store this information for future +trace streams created for this process. +.SH RETURN VALUE +.LP +No return value is defined for the \fIposix_trace_event\fP() function. +.LP +Upon successful completion, the \fIposix_trace_eventid_open\fP() function +shall return a value of zero. Otherwise, it shall +return the corresponding error number. The \fIposix_trace_eventid_open\fP() +function stores the trace event type identifier value +in the object pointed to by \fIevent_id\fP, if successful. +.SH ERRORS +.LP +The \fIposix_trace_eventid_open\fP() function shall fail if: +.TP 7 +.B ENAMETOOLONG +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 +\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_start\fP() , +\fIposix_trace_trid_eventid_open\fP() , the Base Definitions volume +of +IEEE\ Std\ 1003.1-2001, \fI<sys/types.h>\fP, \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 . |