xsh_chap02_11.html

IEEE 1003.1-2003, Single Unix Specification v3

contain at least the following members:</p>

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

<tr valign="top">
<td align="left">
<p class="tent"><b>trace_event_id_t</b></p>
</td>
<td align="left">
<p class="tent"><i>posix_event_id</i></p>
</td>
<td align="left">
<p class="tent">Trace event type identification.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>pid_t</b></p>
</td>
<td align="left">
<p class="tent"><i>posix_pid</i></p>
</td>
<td align="left">
<p class="tent">Process ID of the process that generated the trace event.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>void *</b></p>
</td>
<td align="left">
<p class="tent"><i>posix_prog_address</i></p>
</td>
<td align="left">
<p class="tent">Address at which the trace point was invoked.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>int</b></p>
</td>
<td align="left">
<p class="tent"><i>posix_truncation_status</i></p>
</td>
<td align="left">
<p class="tent">Status about the truncation of the data associated with this trace event.</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent"><b>struct timespec</b></p>
</td>
<td align="left">
<p class="tent"><i>posix_timestamp</i></p>
</td>
<td align="left">
<p class="tent">Time at which the trace event was generated.</p>
</td>
</tr>
</table>
</center>

<p>In addition, if the Trace option and the Threads option are both supported, the <b>posix_trace_event_info</b> structure defined
in <a href="../basedefs/trace.h.html"><i>&lt;trace.h&gt;</i></a> shall contain the following additional member:</p>

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

<tr valign="top">
<td align="left">
<p class="tent"><b>pthread_t</b></p>
</td>
<td align="left">
<p class="tent"><i>posix_thread_id</i></p>
</td>
<td align="left">
<p class="tent">Thread ID of the thread that generated the trace event.</p>
</td>
</tr>
</table>
</center>

<p>The <i>posix_event_id</i> member represents the identification of the trace event type and its value is not directly defined by
the user. This identification is returned by a call to one of the following functions: <a href=
"../functions/posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a>, <a href=
"../functions/posix_trace_eventtypelist_getnext_id.html"><i>posix_trace_eventtypelist_getnext_id</i>()</a>, or <a href=
"../functions/posix_trace_eventid_open.html"><i>posix_trace_eventid_open</i>()</a>. The name of the trace event type can be
obtained by calling <a href="../functions/posix_trace_eventid_get_name.html"><i>posix_trace_eventid_get_name</i>()</a>.</p>

<p>The <i>posix_pid</i> is the process identifier of the traced process which generated the trace event. If the
<i>posix_event_id</i> member is one of the implementation-defined system trace events and that trace event is not associated with
any process, the <i>posix_pid</i> member shall be set to zero.</p>

<p>For a user trace event, the <i>posix_prog_address</i> member is the process mapped address of the point at which the associated
call to the <a href="../functions/posix_trace_event.html"><i>posix_trace_event</i>()</a> function was made. For a system trace
event, if the trace event is caused by a system service explicitly called by the application, the <i>posix_prog_address</i> member
shall be the address of the process at the point where the call to that system service was made.</p>

<p>The <i>posix_truncation_status</i> member defines whether the data associated with a trace event has been truncated at the time
the trace event was generated, or at the time the trace event was read from the trace stream, or (if the Trace Log option is
supported) from the trace log (see the <i>event</i> argument from the <a href=
"../functions/posix_trace_getnext_event.html"><i>posix_trace_getnext_event</i>()</a> function). The <i>posix_truncation_status</i>
member shall have one of the following values defined by manifest constants in the <a href=
"../basedefs/trace.h.html"><i>&lt;trace.h&gt;</i></a> header:</p>

<dl compact>
<dt>POSIX_TRACE_NOT_TRUNCATED</dt>

<dd><br>
All the traced data is available.</dd>

<dt>POSIX_TRACE_TRUNCATED_RECORD</dt>

<dd><br>
Data was truncated at the time the trace event was generated.</dd>

<dt>POSIX_TRACE_TRUNCATED_READ</dt>

<dd><br>
Data was truncated at the time the trace event was read from a trace stream or a trace log because the reader's buffer was too
small. This truncation status overrides the POSIX_TRACE_TRUNCATED_RECORD status.</dd>
</dl>

<p>The <i>posix_timestamp</i> member shall be the time at which the trace event was generated. The clock used is
implementation-defined, but the resolution of this clock can be retrieved by a call to the <a href=
"../functions/posix_trace_attr_getclockres.html"><i>posix_trace_attr_getclockres</i>()</a> function.</p>

<p>If the Threads option is supported in addition to the Trace option:</p>

<ul>
<li>
<p>The <i>posix_thread_id</i> member is the identifier of the thread that generated the trace event. If the <i>posix_event_id</i>
member is one of the implementation-defined system trace events and that trace event is not associated with any thread, the
<i>posix_thread_id</i> member shall be set to zero.</p>
</li>
</ul>

<p>Otherwise, this member is undefined.</p>

<h5><a name="tag_02_11_01_04"></a>Trace Stream Attributes</h5>

<p>Trace streams have attributes that compose the <b>posix_trace_attr_t</b> trace stream attributes object. This object shall
contain at least the following attributes:</p>

<ul>
<li>
<p>The <i>generation-version</i> attribute identifies the origin and version of the trace system.</p>
</li>

<li>
<p>The <i>trace-name</i> attribute is a character string defined by the trace controller, and that identifies the trace stream.</p>
</li>

<li>
<p>The <i>creation-time</i> attribute represents the time of the creation of the trace stream.</p>
</li>

<li>
<p>The <i>clock-resolution</i> attribute defines the clock resolution of the clock used to generate timestamps.</p>
</li>

<li>
<p>The <i>stream-min-size</i> attribute defines the minimum size in bytes of the trace stream strictly reserved for the trace
events.</p>
</li>

<li>
<p>The <i>stream-full-policy</i> attribute defines the policy followed when the trace stream is full; its value is
POSIX_TRACE_LOOP, POSIX_TRACE_UNTIL_FULL, or POSIX_TRACE_FLUSH.</p>
</li>

<li>
<p>The <i>max-data-size</i> attribute defines the maximum record size in bytes of a trace event.</p>
</li>
</ul>

<p>In addition, if the Trace option and the Trace Inherit option are both supported, the <b>posix_trace_attr_t</b> trace stream
creation attributes object shall contain at least the following attributes:</p>

<ul>
<li>
<p>The <i>inheritance</i> attribute specifies whether a newly created trace stream will inherit tracing in its parent's process
trace stream. It is either POSIX_TRACE_INHERITED or POSIX_TRACE_CLOSE_FOR_CHILD.</p>
</li>
</ul>

<p>In addition, if the Trace option and the Trace Log option are both supported, the <b>posix_trace_attr_t</b> trace stream
creation attributes object shall contain at least the following attribute:</p>

<ul>
<li>
<p>If the file type corresponding to the trace log supports the POSIX_TRACE_LOOP or the POSIX_TRACE_UNTIL_FULL policies, the
<i>log-max-size</i> attribute defines the maximum size in bytes of the trace log associated with an active trace stream. Other
stream data-for example, trace attribute values-shall not be included in this size.</p>
</li>

<li>
<p>The <i>log-full-policy</i> attribute defines the policy of a trace log associated with an active trace stream to be
POSIX_TRACE_LOOP, POSIX_TRACE_UNTIL_FULL, or POSIX_TRACE_APPEND.</p>
</li>
</ul>

<h4><a name="tag_02_11_02"></a>Trace Event Type Definitions</h4>

<h5><a name="tag_02_11_02_01"></a>System Trace Event Type Definitions</h5>

<p>The following system trace event types, defined in the <a href="../basedefs/trace.h.html"><i>&lt;trace.h&gt;</i></a> header,
track the invocation of the trace operations:</p>

<ul>
<li>
<p>POSIX_TRACE_START shall be associated with a trace start operation.</p>
</li>

<li>
<p>POSIX_TRACE_STOP shall be associated with a trace stop operation.</p>
</li>

<li>
<p>If the Trace Event Filter option is supported, POSIX_TRACE_FILTER shall be associated with a trace event type filter change
operation.</p>
</li>
</ul>

<p>The following system trace event types, defined in the <a href="../basedefs/trace.h.html"><i>&lt;trace.h&gt;</i></a> header,
report operational trace events:</p>

<ul>
<li>
<p>POSIX_TRACE_OVERFLOW shall mark the beginning of a trace overflow condition.</p>
</li>

<li>
<p>POSIX_TRACE_RESUME shall mark the end of a trace overflow condition.</p>
</li>

<li>
<p>If the Trace Log option is supported, POSIX_TRACE_FLUSH_START shall mark the beginning of a flush operation.</p>
</li>

<li>
<p>If the Trace Log option is supported, POSIX_TRACE_FLUSH_STOP shall mark the end of a flush operation.</p>
</li>

<li>
<p>If an implementation-defined trace error condition is reported, it shall be marked POSIX_TRACE_ERROR.</p>
</li>
</ul>

<p>The interpretation of a trace stream or a trace log by a trace analyzer process relies on the information recorded for each
trace event, and also on system trace events that indicate the invocation of trace control operations and trace system operational
trace events.</p>

<p>The POSIX_TRACE_START and POSIX_TRACE_STOP trace events specify the time windows during which the trace stream is running.</p>

<ul>
<li>
<p>The POSIX_TRACE_STOP trace event with an associated data that is equal to zero indicates a call of the function <a href=
"../functions/posix_trace_stop.html"><i>posix_trace_stop</i>()</a>.</p>
</li>

<li>
<p>The POSIX_TRACE_STOP trace event with an associated data that is different from zero indicates an automatic stop of the trace
stream (see <a href="posix_trace_attr_getstreamfullpolicy.html"><i>posix_trace_attr_getstreamfullpolicy</i>()</a> ).</p>
</li>
</ul>

<p>The POSIX_TRACE_FILTER trace event indicates that a trace event type filter value changed while the trace stream was
running.</p>

<p>The POSIX_TRACE_ERROR serves to inform the analyzer process that an implementation-defined internal error of the trace system
occurred.</p>

<p>The POSIX_TRACE_OVERFLOW trace event shall be reported with a timestamp equal to the timestamp of the first trace event
overwritten. This is an indication that some generated trace events have been lost.</p>

<p>The POSIX_TRACE_RESUME trace event shall be reported with a timestamp equal to the timestamp of the first valid trace event
reported after the overflow condition ends and shall be reported before this first valid trace event. This is an indication that
the trace system is reliably recording trace events after an overflow condition.</p>

<p>Each of these trace event types shall be defined by a constant trace event name and a <b>trace_event_id_t</b> constant; trace
event data is associated with some of these trace events.</p>

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

<center><b><a name="tagtcjh_3"></a> Table: Trace Option: 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">None.</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">