1726 lines
48 KiB
HTML
1726 lines
48 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>System Interfaces Chapter 2</title>
|
|
</head>
|
|
<body>
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3">
|
|
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001</font></center>
|
|
|
|
<hr size="2" noshade>
|
|
<h3><a name="tag_02_11"></a>Tracing</h3>
|
|
|
|
<div class="box">
|
|
<p><sup>[<a href="javascript:open_code('TRC')">TRC</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
|
|
This section describes extensions to support tracing of user applications. This functionality is dependent on support of the Trace
|
|
option (and the rest of this section is not further marked for this option). <img src="../images/opt-end.gif" alt="[Option End]"
|
|
border="0"></p>
|
|
</div>
|
|
|
|
<p>The tracing facilities defined in IEEE Std 1003.1-2001 allow a process to select a set of trace event types, to
|
|
activate a trace stream of the selected trace events as they occur in the flow of execution, and to retrieve the recorded trace
|
|
events.</p>
|
|
|
|
<p>The tracing operation relies on three logically different components: the traced process, the controller process, and the
|
|
analyzer process. During the execution of the traced process, when a trace point is reached, a trace event is recorded into the
|
|
trace streams created for that process in which the associated trace event type identifier is not being filtered out. The
|
|
controller process controls the operation of recording the trace events into the trace stream. It shall be able to:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>Initialize the attributes of a trace stream</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Create the trace stream (for a specified traced process) using those attributes</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Start and stop tracing for the trace stream</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Filter the type of trace events to be recorded, if the Trace Event Filter option is supported</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>Shut a trace stream down</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>These operations can be done for an active trace stream. The analyzer process retrieves the traced events either at runtime,
|
|
when the trace stream has not yet been shut down, but is still recording trace events; or after opening a trace log that had been
|
|
previously recorded and shut down. These three logically different operations can be performed by the same process, or can be
|
|
distributed into different processes.</p>
|
|
|
|
<p>A trace stream identifier can be created by a call to <a href=
|
|
"../functions/posix_trace_create.html"><i>posix_trace_create</i>()</a>, <a href=
|
|
"../functions/posix_trace_create_withlog.html"><i>posix_trace_create_withlog</i>()</a>, or <a href=
|
|
"../functions/posix_trace_open.html"><i>posix_trace_open</i>()</a>. The <a href=
|
|
"../functions/posix_trace_create.html"><i>posix_trace_create</i>()</a> and <a href=
|
|
"../functions/posix_trace_create_withlog.html"><i>posix_trace_create_withlog</i>()</a> functions should be used by a controller
|
|
process. The <a href="../functions/posix_trace_open.html"><i>posix_trace_open</i>()</a> should be used by an analyzer process.</p>
|
|
|
|
<p>The tracing functions can serve different purposes. One purpose is debugging the possibly pre-instrumented code, while another
|
|
is post-mortem fault analysis. These two potential uses differ in that the first requires pre-filtering capabilities to avoid
|
|
overwhelming the trace stream and permits focusing on expected information; while the second needs comprehensive trace capabilities
|
|
in order to be able to record all types of information.</p>
|
|
|
|
<p>The events to be traced belong to two classes:</p>
|
|
|
|
<ol>
|
|
<li>
|
|
<p>User trace events (generated by the application instrumentation)</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>System trace events (generated by the operating system)</p>
|
|
</li>
|
|
</ol>
|
|
|
|
<p>The trace interface defines several system trace event types associated with control of and operation of the trace stream. This
|
|
small set of system trace events includes the minimum required to interpret correctly the trace event information present in the
|
|
stream. Other desirable system trace events for some particular application profile may be implemented and are encouraged; for
|
|
example, process and thread scheduling, signal occurrence, and so on.</p>
|
|
|
|
<p>Each traced process shall have a mapping of the trace event names to trace event type identifiers that have been defined for
|
|
that process. Each active trace stream shall have a mapping that incorporates all the trace event type identifiers predefined by
|
|
the trace system plus all the mappings of trace event names to trace event type identifiers of the processes that are being traced
|
|
into that trace stream. These mappings are defined from the instrumented application by calling the <a href=
|
|
"../functions/posix_trace_eventid_open.html"><i>posix_trace_eventid_open</i>()</a> function and from the controller process by
|
|
calling the <a href="../functions/posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a> function. For a
|
|
pre-recorded trace stream, the list of trace event types is obtained from the pre-recorded trace log.</p>
|
|
|
|
<p>The <i>st_ctime</i> and <i>st_mtime</i> fields of a file associated with an active trace stream shall be marked for update every
|
|
time any of the tracing operations modifies that file.</p>
|
|
|
|
<p>The <i>st_atime</i> field of a file associated with a trace stream shall be marked for update every time any of the tracing
|
|
operations causes data to be read from that file.</p>
|
|
|
|
<p>Results are undefined if the application performs any operation on a file descriptor associated with an active or pre-recorded
|
|
trace stream until <a href="../functions/posix_trace_shutdown.html"><i>posix_trace_shutdown</i>()</a> or <a href=
|
|
"../functions/posix_trace_close.html"><i>posix_trace_close</i>()</a> is called for that trace stream.</p>
|
|
|
|
<p>The main purpose of this option is to define a complete set of functions and concepts that allow a conforming application to be
|
|
traced from creation to termination, whatever its realtime constraints and properties.</p>
|
|
|
|
<h4><a name="tag_02_11_01"></a>Tracing Data Definitions</h4>
|
|
|
|
<h5><a name="tag_02_11_01_01"></a>Structures</h5>
|
|
|
|
<p>The <a href="../basedefs/trace.h.html"><i><trace.h></i></a> header shall define the <i>posix_trace_status_info</i> and
|
|
<i>posix_trace_event_info</i> structures described below. Implementations may add extensions to these structures.</p>
|
|
|
|
<h5><a name="tag_02_11_01_02"></a>posix_trace_status_info Structure</h5>
|
|
|
|
<p>To facilitate control of a trace stream, information about the current state of an active trace stream can be obtained
|
|
dynamically. This structure is returned by a call to the <a href=
|
|
"../functions/posix_trace_get_status.html"><i>posix_trace_get_status</i>()</a> function.</p>
|
|
|
|
<p>The <b>posix_trace_status_info</b> structure defined in <a href="../basedefs/trace.h.html"><i><trace.h></i></a> shall
|
|
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>int</b></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><i>posix_stream_status</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">The operating mode of the trace stream.</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_stream_full_status</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">The full status of the trace stream.</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_stream_overrun_status</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Indicates whether trace events were lost in the trace stream.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>If the Trace Log option is supported in addition to the Trace option, the <b>posix_trace_status_info</b> structure defined in <a
|
|
href="../basedefs/trace.h.html"><i><trace.h></i></a> shall contain at least the following additional 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>int</b></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"><i>posix_stream_flush_status</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Indicates whether a flush is in progress.</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_stream_flush_error</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Indicates whether any error occurred during the last flush operation.</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_log_overrun_status</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">Indicates whether trace events were lost in the trace log.</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_log_full_status</i></p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">The full status of the trace log.</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
<p>The <i>posix_stream_status</i> member indicates the operating mode of the trace stream and shall have one of the following
|
|
values defined by manifest constants in the <a href="../basedefs/trace.h.html"><i><trace.h></i></a> header:</p>
|
|
|
|
<dl compact>
|
|
<dt>POSIX_TRACE_RUNNING</dt>
|
|
|
|
<dd><br>
|
|
Tracing is in progress; that is, the trace stream is accepting trace events.</dd>
|
|
|
|
<dt>POSIX_TRACE_SUSPENDED</dt>
|
|
|
|
<dd><br>
|
|
The trace stream is not accepting trace events. The tracing operation has not yet started or has stopped, either following a <a
|
|
href="../functions/posix_trace_stop.html"><i>posix_trace_stop</i>()</a> function call or because the trace resources are
|
|
exhausted.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>posix_stream_full_status</i> member indicates the full status of the trace stream, and it shall have one of the following
|
|
values defined by manifest constants in the <a href="../basedefs/trace.h.html"><i><trace.h></i></a> header:</p>
|
|
|
|
<dl compact>
|
|
<dt>POSIX_TRACE_FULL</dt>
|
|
|
|
<dd><br>
|
|
The space in the trace stream for trace events is exhausted.</dd>
|
|
|
|
<dt>POSIX_TRACE_NOT_FULL</dt>
|
|
|
|
<dd><br>
|
|
There is still space available in the trace stream.</dd>
|
|
</dl>
|
|
|
|
<p>The combination of the <i>posix_stream_status</i> and <i>posix_stream_full_status</i> members also indicates the actual status
|
|
of the stream. The status shall be interpreted as follows:</p>
|
|
|
|
<dl compact>
|
|
<dt>POSIX_TRACE_RUNNING and POSIX_TRACE_NOT_FULL</dt>
|
|
|
|
<dd><br>
|
|
This status combination indicates that tracing is in progress, and there is space available for recording more trace events.</dd>
|
|
|
|
<dt>POSIX_TRACE_RUNNING and POSIX_TRACE_FULL</dt>
|
|
|
|
<dd><br>
|
|
This status combination indicates that tracing is in progress and that the trace stream is full of trace events. This status
|
|
combination cannot occur unless the <i>stream-full-policy</i> is set to POSIX_TRACE_LOOP. The trace stream contains trace events
|
|
recorded during a moving time window of prior trace events, and some older trace events may have been overwritten and thus
|
|
lost.</dd>
|
|
|
|
<dt>POSIX_TRACE_SUSPENDED and POSIX_TRACE_NOT_FULL</dt>
|
|
|
|
<dd><br>
|
|
This status combination indicates that tracing has not yet been started, has been stopped by the <a href=
|
|
"../functions/posix_trace_stop.html"><i>posix_trace_stop</i>()</a> function, or has been cleared by the <a href=
|
|
"../functions/posix_trace_clear.html"><i>posix_trace_clear</i>()</a> function.</dd>
|
|
|
|
<dt>POSIX_TRACE_SUSPENDED and POSIX_TRACE_FULL</dt>
|
|
|
|
<dd><br>
|
|
This status combination indicates that tracing has been stopped by the implementation because the <i>stream-full-policy</i>
|
|
attribute was POSIX_TRACE_UNTIL_FULL and trace resources were exhausted, or that the trace stream was stopped by the function <a
|
|
href="../functions/posix_trace_stop.html"><i>posix_trace_stop</i>()</a> at a time when trace resources were exhausted.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>posix_stream_overrun_status</i> member indicates whether trace events were lost in the trace stream, and shall have one
|
|
of the following values defined by manifest constants in the <a href="../basedefs/trace.h.html"><i><trace.h></i></a>
|
|
header:</p>
|
|
|
|
<dl compact>
|
|
<dt>POSIX_TRACE_OVERRUN</dt>
|
|
|
|
<dd><br>
|
|
At least one trace event was lost and thus was not recorded in the trace stream.</dd>
|
|
|
|
<dt>POSIX_TRACE_NO_OVERRUN</dt>
|
|
|
|
<dd><br>
|
|
No trace events were lost.</dd>
|
|
</dl>
|
|
|
|
<p>When the corresponding trace stream is created, the <i>posix_stream_overrun_status</i> member shall be set to
|
|
POSIX_TRACE_NO_OVERRUN.</p>
|
|
|
|
<p>Whenever an overrun occurs, the <i>posix_stream_overrun_status</i> member shall be set to POSIX_TRACE_OVERRUN.</p>
|
|
|
|
<p>An overrun occurs when:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The policy is POSIX_TRACE_LOOP and a recorded trace event is overwritten.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>The policy is POSIX_TRACE_UNTIL_FULL and the trace stream is full when a trace event is generated.</p>
|
|
</li>
|
|
|
|
<li>
|
|
<p>If the Trace Log option is supported, the policy is POSIX_TRACE_FLUSH and at least one trace event is lost while flushing the
|
|
trace stream to the trace log.</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>The <i>posix_stream_overrun_status</i> member is reset to zero after its value is read.</p>
|
|
|
|
<p>If the Trace Log option is supported in addition to the Trace option, the <i>posix_stream_flush_status</i>,
|
|
<i>posix_stream_flush_error</i>, <i>posix_log_overrun_status</i>, and <i>posix_log_full_status</i> members are defined as follows;
|
|
otherwise, they are undefined.</p>
|
|
|
|
<p>The <i>posix_stream_flush_status</i> member indicates whether a flush operation is being performed and shall have one of the
|
|
following values defined by manifest constants in the header <a href="../basedefs/trace.h.html"><i><trace.h></i></a>:</p>
|
|
|
|
<dl compact>
|
|
<dt>POSIX_TRACE_FLUSHING</dt>
|
|
|
|
<dd><br>
|
|
The trace stream is currently being flushed to the trace log.</dd>
|
|
|
|
<dt>POSIX_TRACE_NOT_FLUSHING</dt>
|
|
|
|
<dd><br>
|
|
No flush operation is in progress.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>posix_stream_flush_status</i> member shall be set to POSIX_TRACE_FLUSHING if a flush operation is in progress either due
|
|
to a call to the <a href="../functions/posix_trace_flush.html"><i>posix_trace_flush</i>()</a> function (explicit or caused by a
|
|
trace stream shutdown operation) or because the trace stream has become full with the <i>stream-full-policy</i> attribute set to
|
|
POSIX_TRACE_FLUSH. The <i>posix_stream_flush_status</i> member shall be set to POSIX_TRACE_NOT_FLUSHING if no flush operation is in
|
|
progress.</p>
|
|
|
|
<p>The <i>posix_stream_flush_error</i> member shall be set to zero if no error occurred during flushing. If an error occurred
|
|
during a previous flushing operation, the <i>posix_stream_flush_error</i> member shall be set to the value of the first error that
|
|
occurred. If more than one error occurs while flushing, error values after the first shall be discarded. The
|
|
<i>posix_stream_flush_error</i> member is reset to zero after its value is read.</p>
|
|
|
|
<p>The <i>posix_log_overrun_status</i> member indicates whether trace events were lost in the trace log, and shall have one of the
|
|
following values defined by manifest constants in the <a href="../basedefs/trace.h.html"><i><trace.h></i></a> header:</p>
|
|
|
|
<dl compact>
|
|
<dt>POSIX_TRACE_OVERRUN</dt>
|
|
|
|
<dd><br>
|
|
At least one trace event was lost.</dd>
|
|
|
|
<dt>POSIX_TRACE_NO_OVERRUN</dt>
|
|
|
|
<dd><br>
|
|
No trace events were lost.</dd>
|
|
</dl>
|
|
|
|
<p>When the corresponding trace stream is created, the <i>posix_log_overrun_status</i> member shall be set to
|
|
POSIX_TRACE_NO_OVERRUN. Whenever an overrun occurs, this status shall be set to POSIX_TRACE_OVERRUN. The
|
|
<i>posix_log_overrun_status</i> member is reset to zero after its value is read.</p>
|
|
|
|
<p>The <i>posix_log_full_status</i> member indicates the full status of the trace log, and it shall have one of the following
|
|
values defined by manifest constants in the <a href="../basedefs/trace.h.html"><i><trace.h></i></a> header:</p>
|
|
|
|
<dl compact>
|
|
<dt>POSIX_TRACE_FULL</dt>
|
|
|
|
<dd><br>
|
|
The space in the trace log is exhausted.</dd>
|
|
|
|
<dt>POSIX_TRACE_NOT_FULL</dt>
|
|
|
|
<dd><br>
|
|
There is still space available in the trace log.</dd>
|
|
</dl>
|
|
|
|
<p>The <i>posix_log_full_status</i> member is only meaningful if the <i>log-full-policy</i> attribute is either
|
|
POSIX_TRACE_UNTIL_FULL or POSIX_TRACE_LOOP.</p>
|
|
|
|
<p>For an active trace stream without log, that is created by the <a href=
|
|
"../functions/posix_trace_create.html"><i>posix_trace_create</i>()</a> function, the <i>posix_log_overrun_status</i> member shall
|
|
be set to POSIX_TRACE_NO_OVERRUN and the <i>posix_log_full_status</i> member shall be set to POSIX_TRACE_NOT_FULL.</p>
|
|
|
|
<h5><a name="tag_02_11_01_03"></a>posix_trace_event_info Structure</h5>
|
|
|
|
<p>The trace event structure <b>posix_trace_event_info</b> contains the information for one recorded trace event. This structure is
|
|
returned by the set of functions <a href="../functions/posix_trace_getnext_event.html"><i>posix_trace_getnext_event</i>()</a>, <a
|
|
href="../functions/posix_trace_timedgetnext_event.html"><i>posix_trace_timedgetnext_event</i>()</a>, and <a href=
|
|
"../functions/posix_trace_trygetnext_event.html"><i>posix_trace_trygetnext_event</i>()</a>.</p>
|
|
|
|
<p>The <b>posix_trace_event_info</b> structure defined in <a href="../basedefs/trace.h.html"><i><trace.h></i></a> shall
|
|
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><trace.h></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><trace.h></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><trace.h></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><trace.h></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> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>_</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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_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>
|
|
</table>
|
|
</center>
|
|
|
|
<p>If the Trace option and the Trace Event Filter option are both supported, and if the Trace Log option is not supported, the
|
|
following predefined system trace events in <a href="#tagtcjh_4">Trace and Trace Event Filter Options: System Trace Events</a>
|
|
shall be defined:<br>
|
|
</p>
|
|
|
|
<center><b><a name="tagtcjh_4"></a> Table: Trace 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> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>_</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">new_event_filter</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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>
|
|
</table>
|
|
</center>
|
|
|
|
<p>If the Trace option and the Trace Log option are both supported, and if the Trace Event Filter option is not supported, the
|
|
following predefined system trace events in <a href="#tagtcjh_5">Trace and Trace Log Options: System Trace Events</a> shall be
|
|
defined:<br>
|
|
</p>
|
|
|
|
<center><b><a name="tagtcjh_5"></a> Table: Trace and Trace Log 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> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>_</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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_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>
|
|
|
|
<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> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b>_</b></p>
|
|
</th>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<th align="center">
|
|
<p class="tent"><b> </b></p>
|
|
</th>
|
|
<th align="center">
|
|
<p class="tent"><b> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">new_event_filter</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent">_</p>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr valign="top">
|
|
<td align="left">
|
|
<p class="tent"> </p>
|
|
</td>
|
|
<td align="left">
|
|
<p class="tent"> </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><trace.h></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">UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
</font> [ <a href="../mindex.html">Main Index</a>]</center>
|
|
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|