xsh_chap02_11.html

IEEE 1003.1-2003, Single Unix Specification v3

</center>

<p>If the Trace option, the Trace Event Filter option, and the Trace Log option are all supported, the following predefined system
trace events in <a href="#tagtcjh_6">Trace, Trace Log, and Trace Event Filter Options: System Trace Events</a> shall be
defined:<br>
</p>

<center><b><a name="tagtcjh_6"></a> Table: Trace, Trace Log, and Trace Event Filter Options: System Trace Events</b></center>

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th align="center">
<p class="tent"><b>Event Name</b></p>
</th>
<th align="center">
<p class="tent"><b>Constant</b></p>
</th>
<th align="center">
<p class="tent"><b>Associated Data</b></p>
</th>
</tr>

<tr valign="top">
<th align="center">
<p class="tent"><b>&nbsp;</b></p>
</th>
<th align="center">
<p class="tent"><b>&nbsp;</b></p>
</th>
<th align="center">
<p class="tent"><b>_</b></p>
</th>
</tr>

<tr valign="top">
<th align="center">
<p class="tent"><b>&nbsp;</b></p>
</th>
<th align="center">
<p class="tent"><b>&nbsp;</b></p>
</th>
<th align="center">
<p class="tent"><b>Data Type</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_error</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_ERROR</p>
</td>
<td align="left">
<p class="tent">error</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">_</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent"><b>int</b></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_start</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_START</p>
</td>
<td align="left">
<p class="tent">event_filter</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">_</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent"><b>trace_event_set_t</b></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_stop</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_STOP</p>
</td>
<td align="left">
<p class="tent">auto</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">_</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent"><b>int</b></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_filter</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_FILTER</p>
</td>
<td align="left">
<p class="tent">old_event_filter</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">new_event_filter</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">_</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent">&nbsp;</p>
</td>
<td align="left">
<p class="tent"><b>trace_event_set_t</b></p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_overflow</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_OVERFLOW</p>
</td>
<td align="left">
<p class="tent">None.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_resume</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_RESUME</p>
</td>
<td align="left">
<p class="tent">None.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_flush_start</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_FLUSH_START</p>
</td>
<td align="left">
<p class="tent">None.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_flush_stop</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_FLUSH_STOP</p>
</td>
<td align="left">
<p class="tent">None.</p>
</td>
</tr>
</table>
</center>

<h5><a name="tag_02_11_02_02"></a>User Trace Event Type Definitions</h5>

<p>The user trace event POSIX_TRACE_UNNAMED_USEREVENT is defined in the <a href=
"../basedefs/trace.h.html"><i>&lt;trace.h&gt;</i></a> header. If the limit of per-process user trace event names represented by
{TRACE_USER_EVENT_MAX} has already been reached, this predefined user event shall be returned when the application tries to
register more events than allowed. The data associated with this trace event is application-defined.</p>

<p>The following predefined user trace event in <a href="#tagtcjh_7">Trace Option: User Trace Event</a> shall be defined:<br>
</p>

<center><b><a name="tagtcjh_7"></a> Table: Trace Option: User Trace Event</b></center>

<center>
<table border="1" cellpadding="3" align="center">
<tr valign="top">
<th align="center">
<p class="tent"><b>Event Name</b></p>
</th>
<th align="center">
<p class="tent"><b>Constant</b></p>
</th>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">posix_trace_unnamed_userevent</p>
</td>
<td align="left">
<p class="tent">POSIX_TRACE_UNNAMED_USEREVENT</p>
</td>
</tr>
</table>
</center>

<h4><a name="tag_02_11_03"></a>Trace Functions</h4>

<p>The trace interface is built and structured to improve portability through use of trace data of opaque type. The object-oriented
approach for the manipulation of trace attributes and trace event type identifiers requires definition of many constructor and
selector functions which operate on these opaque types. Also, the trace interface must support several different tracing roles. To
facilitate reading the trace interface, the trace functions are grouped into small functional sets supporting the three different
roles:</p>

<ul>
<li>
<p>A trace controller process requires functions to set up and customize all the resources needed to run a trace stream,
including:</p>

<ul>
<li>
<p>Attribute initialization and destruction ( <a href=
"../functions/posix_trace_attr_init.html"><i>posix_trace_attr_init</i>()</a>)</p>
</li>

<li>
<p>Identification information manipulation ( <a href=
"../functions/posix_trace_attr_getgenversion.html"><i>posix_trace_attr_getgenversion</i>()</a>)</p>
</li>

<li>
<p>Trace system behavior modification ( <a href=
"../functions/posix_trace_attr_getinherited.html"><i>posix_trace_attr_getinherited</i>()</a>)</p>
</li>

<li>
<p>Trace stream and trace log size set ( <a href=
"../functions/posix_trace_attr_getmaxusereventsize.html"><i>posix_trace_attr_getmaxusereventsize</i>()</a>)</p>
</li>

<li>
<p>Trace stream creation, flush, and shutdown ( <a href="../functions/posix_trace_create.html"><i>posix_trace_create</i>()</a>)</p>
</li>

<li>
<p>Trace stream and trace log clear ( <a href="../functions/posix_trace_clear.html"><i>posix_trace_clear</i>()</a>)</p>
</li>

<li>
<p>Trace event type identifier manipulation ( <a href=
"../functions/posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a>)</p>
</li>

<li>
<p>Trace event type identifier list exploration ( <a href=
"../functions/posix_trace_eventtypelist_getnext_id.html"><i>posix_trace_eventtypelist_getnext_id</i>()</a>)</p>
</li>

<li>
<p>Trace event type set manipulation ( <a href=
"../functions/posix_trace_eventset_empty.html"><i>posix_trace_eventset_empty</i>()</a>)</p>
</li>

<li>
<p>Trace event type filter set ( <a href="../functions/posix_trace_set_filter.html"><i>posix_trace_set_filter</i>()</a>)</p>
</li>

<li>
<p>Trace stream start and stop ( <a href="../functions/posix_trace_start.html"><i>posix_trace_start</i>()</a>)</p>
</li>

<li>
<p>Trace stream information and status read ( <a href=
"../functions/posix_trace_get_attr.html"><i>posix_trace_get_attr</i>()</a>)</p>
</li>
</ul>
</li>

<li>
<p>A traced process requires functions to instrument trace points:</p>

<ul>
<li>
<p>Trace event type identifiers definition and trace points insertion ( <a href=
"../functions/posix_trace_event.html"><i>posix_trace_event</i>()</a>)</p>
</li>
</ul>
</li>

<li>
<p>A trace analyzer process requires functions to retrieve information from a trace stream and trace log:</p>

<ul>
<li>
<p>Identification information read ( <a href=
"../functions/posix_trace_attr_getgenversion.html"><i>posix_trace_attr_getgenversion</i>()</a>)</p>
</li>

<li>
<p>Trace system behavior information read ( <a href=
"../functions/posix_trace_attr_getinherited.html"><i>posix_trace_attr_getinherited</i>()</a>)</p>
</li>

<li>
<p>Trace stream and trace log size get ( <a href=
"../functions/posix_trace_attr_getmaxusereventsize.html"><i>posix_trace_attr_getmaxusereventsize</i>()</a>)</p>
</li>

<li>
<p>Trace event type identifier manipulation ( <a href=
"../functions/posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a>)</p>
</li>

<li>
<p>Trace event type identifier list exploration ( <a href=
"../functions/posix_trace_eventtypelist_getnext_id.html"><i>posix_trace_eventtypelist_getnext_id</i>()</a>)</p>
</li>

<li>
<p>Trace log open, rewind, and close ( <a href="../functions/posix_trace_open.html"><i>posix_trace_open</i>()</a>)</p>
</li>

<li>
<p>Trace stream information and status read ( <a href=
"../functions/posix_trace_get_attr.html"><i>posix_trace_get_attr</i>()</a>)</p>
</li>

<li>
<p>Trace event read ( <a href="../functions/posix_trace_getnext_event.html"><i>posix_trace_getnext_event</i>()</a>)</p>
</li>
</ul>
</li>
</ul>



<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>