man3p/posix_trace_event.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "POSIX_TRACE_EVENT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" posix_trace_event
   4 .SH NAME
   5 posix_trace_event, posix_trace_eventid_open \- trace functions for
   6 instrumenting application code
   7 (\fBTRACING\fP)
   8 .SH SYNOPSIS
   9 .LP
  10 \fB#include <sys/types.h>
  11 .br
  12 #include <trace.h>
  13 .br
  14 .sp
  15 void posix_trace_event(trace_event_id_t\fP \fIevent_id\fP\fB,
  16 .br
  17 \ \ \ \ \ \  const void *restrict\fP\fIdata_ptr\fP\fB, size_t\fP \fIdata_len\fP\fB);
  18 .br
  19 int posix_trace_eventid_open(const char *restrict\fP \fIevent_name\fP\fB,
  20 .br
  21 \ \ \ \ \ \  trace_event_id_t *restrict\fP \fIevent_id\fP\fB); \fP
  22 \fB
  23 .br
  24 \fP
  25 .SH DESCRIPTION
  26 .LP
  27 The \fIposix_trace_event\fP() function shall record the \fIevent_id\fP
  28 and the user data pointed to by \fIdata_ptr\fP in the
  29 trace stream into which the calling process is being traced and in
  30 which \fIevent_id\fP is not filtered out. If the total size of
  31 the user trace event data represented by \fIdata_len\fP is not greater
  32 than the declared maximum size for user trace event data,
  33 then the \fItruncation-status\fP attribute of the trace event recorded
  34 is POSIX_TRACE_NOT_TRUNCATED. Otherwise, the user trace
  35 event data is truncated to this declared maximum size and the \fItruncation-status\fP
  36 attribute of the trace event recorded is
  37 POSIX_TRACE_TRUNCATED_RECORD.
  38 .LP
  39 If there is no trace stream created for the process or if the created
  40 trace stream is not running, or if the trace event
  41 specified by \fIevent_id\fP is filtered out in the trace stream, the
  42 \fIposix_trace_event\fP() function shall have no effect.
  43 .LP
  44 The \fIposix_trace_eventid_open\fP() function shall associate a user
  45 trace event name with a trace event type identifier for
  46 the calling process. The trace event name is the string pointed to
  47 by the argument \fIevent_name\fP. It shall have a maximum of
  48 {TRACE_EVENT_NAME_MAX} characters (which has the minimum value {_POSIX_TRACE_EVENT_NAME_MAX}).
  49 The number of user trace event type
  50 identifiers that can be defined for any given process is limited by
  51 the maximum value {TRACE_USER_EVENT_MAX}, which has the minimum
  52 value {POSIX_TRACE_USER_EVENT_MAX}.
  53 .LP
  54 If the Trace Inherit option is not supported, the \fIposix_trace_eventid_open\fP()
  55 function shall associate the user trace
  56 event name pointed to by the \fIevent_name\fP argument with a trace
  57 event type identifier that is unique for the traced process,
  58 and is returned in the variable pointed to by the \fIevent_id\fP argument.
  59 If the user trace event name has already been mapped
  60 for the traced process, then the previously assigned trace event type
  61 identifier shall be returned. If the per-process user trace
  62 event name limit represented by {TRACE_USER_EVENT_MAX} has been reached,
  63 the pre-defined POSIX_TRACE_UNNAMED_USEREVENT (see \fITrace Option:
  64 User Trace Event\fP ) user trace event shall be returned.
  65 .LP
  66 If the Trace Inherit option is supported, the \fIposix_trace_eventid_open\fP()
  67 function shall associate the user trace event name
  68 pointed to by the \fIevent_name\fP argument with a trace event type
  69 identifier that is unique for all the processes being traced
  70 in this same trace stream, and is returned in the variable pointed
  71 to by the \fIevent_id\fP argument. If the user trace event name
  72 has already been mapped for the traced processes, then the previously
  73 assigned trace event type identifier shall be returned. If
  74 the per-process user trace event name limit represented by {TRACE_USER_EVENT_MAX}
  75 has been reached, the pre-defined
  76 POSIX_TRACE_UNNAMED_USEREVENT ( \fITrace Option: User Trace Event\fP
  77 ) user trace event
  78 shall be returned.
  79 .TP 7
  80 \fBNote:\fP
  81 The above procedure, together with the fact that multiple processes
  82 can only be traced into the same trace stream by
  83 inheritance, ensure that all the processes that are traced into a
  84 trace stream have the same mapping of trace event names to trace
  85 event type identifiers.
  86 .sp
  87 .LP
  88 If there is no trace stream created, the \fIposix_trace_eventid_open\fP()
  89 function shall store this information for future
  90 trace streams created for this process.
  91 .SH RETURN VALUE
  92 .LP
  93 No return value is defined for the \fIposix_trace_event\fP() function.
  94 .LP
  95 Upon successful completion, the \fIposix_trace_eventid_open\fP() function
  96 shall return a value of zero. Otherwise, it shall
  97 return the corresponding error number. The \fIposix_trace_eventid_open\fP()
  98 function stores the trace event type identifier value
  99 in the object pointed to by \fIevent_id\fP, if successful.
 100 .SH ERRORS
 101 .LP
 102 The \fIposix_trace_eventid_open\fP() function shall fail if:
 103 .TP 7
 104 .B ENAMETOOLONG
 105 The size of the name pointed to by the \fIevent_name\fP argument was
 106 longer than the implementation-defined value
 107 {TRACE_EVENT_NAME_MAX}.
 108 .sp
 109 .LP
 110 \fIThe following sections are informative.\fP
 111 .SH EXAMPLES
 112 .LP
 113 None.
 114 .SH APPLICATION USAGE
 115 .LP
 116 None.
 117 .SH RATIONALE
 118 .LP
 119 None.
 120 .SH FUTURE DIRECTIONS
 121 .LP
 122 None.
 123 .SH SEE ALSO
 124 .LP
 125 \fITrace Option: User Trace Event\fP , \fIposix_trace_start\fP() ,
 126 \fIposix_trace_trid_eventid_open\fP() , the Base Definitions volume
 127 of
 128 IEEE\ Std\ 1003.1-2001, \fI<sys/types.h>\fP, \fI<trace.h>\fP
 129 .SH COPYRIGHT
 130 Portions of this text are reprinted and reproduced in electronic form
 131 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 132 -- Portable Operating System Interface (POSIX), The Open Group Base
 133 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 134 Electrical and Electronics Engineers, Inc and The Open Group. In the
 135 event of any discrepancy between this version and the original IEEE and
 136 The Open Group Standard, the original IEEE and The Open Group Standard
 137 is the referee document. The original Standard can be obtained online at
 138 http://www.opengroup.org/unix/online.html .