📄 xsh_chap02_11.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-2003 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 Traceoption (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, toactivate a trace stream of the selected trace events as they occur in the flow of execution, and to retrieve the recorded traceevents.</p><p>The tracing operation relies on three logically different components: the traced process, the controller process, and theanalyzer process. During the execution of the traced process, when a trace point is reached, a trace event is recorded into thetrace streams created for that process in which the associated trace event type identifier is not being filtered out. Thecontroller 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 beenpreviously recorded and shut down. These three logically different operations can be performed by the same process, or can bedistributed 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 controllerprocess. 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 anotheris post-mortem fault analysis. These two potential uses differ in that the first requires pre-filtering capabilities to avoidoverwhelming the trace stream and permits focusing on expected information; while the second needs comprehensive trace capabilitiesin 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. Thissmall set of system trace events includes the minimum required to interpret correctly the trace event information present in thestream. Other desirable system trace events for some particular application profile may be implemented and are encouraged; forexample, 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 forthat process. Each active trace stream shall have a mapping that incorporates all the trace event type identifiers predefined bythe trace system plus all the mappings of trace event names to trace event type identifiers of the processes that are being tracedinto 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 bycalling the <a href="../functions/posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a> function. For apre-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 everytime 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 tracingoperations 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-recordedtrace 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 betraced 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 obtaineddynamically. 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> shallcontain 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 <ahref="../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 followingvalues 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 <ahref="../functions/posix_trace_stop.html"><i>posix_trace_stop</i>()</a> function call or because the trace resources areexhausted.</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 followingvalues 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 statusof 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 statuscombination cannot occur unless the <i>stream-full-policy</i> is set to POSIX_TRACE_LOOP. The trace stream contains trace eventsrecorded during a moving time window of prior trace events, and some older trace events may have been overwritten and thuslost.</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 <ahref="../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 oneof 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 toPOSIX_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 thetrace 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 thefollowing 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 dueto a call to the <a href="../functions/posix_trace_flush.html"><i>posix_trace_flush</i>()</a> function (explicit or caused by atrace stream shutdown operation) or because the trace stream has become full with the <i>stream-full-policy</i> attribute set toPOSIX_TRACE_FLUSH. The <i>posix_stream_flush_status</i> member shall be set to POSIX_TRACE_NOT_FLUSHING if no flush operation is inprogress.</p><p>The <i>posix_stream_flush_error</i> member shall be set to zero if no error occurred during flushing. If an error occurredduring a previous flushing operation, the <i>posix_stream_flush_error</i> member shall be set to the value of the first error thatoccurred. 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 thefollowing 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 toPOSIX_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 followingvalues 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 eitherPOSIX_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 shallbe 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 isreturned by the set of functions <a href="../functions/posix_trace_getnext_event.html"><i>posix_trace_getnext_event</i>()</a>, <ahref="../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⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -