posix_trace_create.html

IEEE 1003.1-2003, Single Unix Specification v3

<dd><br>
The trace events that have not yet been flushed shall be discarded.</dd>

<dt>POSIX_TRACE_LOOP</dt>

<dd><br>
The trace events that have not yet been flushed shall be written to the beginning of the trace log, overwriting previous trace
events stored there.</dd>

<dt>POSIX_TRACE_APPEND</dt>

<dd><br>
The trace events that have not yet been flushed shall be appended to the trace log.</dd>
</dl>

<img src="../images/opt-end.gif" alt="[Option End]" border="0"> 

<p>The <i>posix_trace_shutdown</i>() function shall stop the tracing of trace events in the trace stream identified by <i>trid</i>,
as if <a href="../functions/posix_trace_stop.html"><i>posix_trace_stop</i>()</a> had been invoked. The
<i>posix_trace_shutdown</i>() function shall free all the resources associated with the trace stream.</p>

<p>The <i>posix_trace_shutdown</i>() function shall not return until all the resources associated with the trace stream have been
freed. When the <i>posix_trace_shutdown</i>() function returns, the <i>trid</i> argument becomes an invalid trace stream
identifier. A call to this function shall unconditionally deallocate the resources regardless of whether all trace events have been
retrieved by the analyzer process. Any thread blocked on one of the <i>trace_getnext_event</i>() functions (which specified this
<i>trid</i>) before this call is unblocked with the error [EINVAL].</p>

<p>If the process exits, invokes a member of the <i><a href="../functions/exec.html">exec</a></i> family of functions, or is
terminated, the trace streams that the process had created and that have not yet been shut down, shall be automatically shut down
as if an explicit call were made to the <i>posix_trace_shutdown</i>() function.</p>

<p><sup>[<a href="javascript:open_code('TRL')">TRL</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
For an active trace stream with log, when the <i>posix_trace_shutdown</i>() function is called, all trace events that have not yet
been flushed to the trace log shall be flushed, as in the <i>posix_trace_flush</i>() function, and the trace log shall be
closed.</p>

<p>When a trace log is closed, all the information that may be retrieved later from the trace log through the trace interface shall
have been written to the trace log. This information includes the trace attributes, the list of trace event types (with the mapping
between trace event names and trace event type identifiers), and the trace status.</p>

<p>In addition, unspecified information shall be written to the trace log to allow detection of a valid trace log during the <a
href="../functions/posix_trace_open.html"><i>posix_trace_open</i>()</a> operation.</p>

<p>The <i>posix_trace_shutdown</i>() function shall not return until all trace events have been flushed. <img src=
"../images/opt-end.gif" alt="[Option End]" border="0"></p>
</blockquote>

<h4><a name="tag_03_462_04"></a>RETURN VALUE</h4>

<blockquote>
<p>Upon successful completion, these functions shall return a value of zero. Otherwise, they shall return the corresponding error
number.</p>

<p>The <i>posix_trace_create</i>() and <sup>[<a href="javascript:open_code('TRL')">TRL</a>]</sup> <img src=
"../images/opt-start.gif" alt="[Option Start]" border="0"> <i>posix_trace_create_withlog</i>() <img src="../images/opt-end.gif"
alt="[Option End]" border="0"> &nbsp;functions store the trace stream identifier value in the object pointed to by <i>trid</i>, if
successful.</p>
</blockquote>

<h4><a name="tag_03_462_05"></a>ERRORS</h4>

<blockquote>
<p>The <i>posix_trace_create</i>() and <sup>[<a href="javascript:open_code('TRL')">TRL</a>]</sup> <img src=
"../images/opt-start.gif" alt="[Option Start]" border="0"> <i>posix_trace_create_withlog</i>() <img src="../images/opt-end.gif"
alt="[Option End]" border="0"> &nbsp;functions shall fail if:</p>

<dl compact>
<dt>[EAGAIN]</dt>

<dd>No more trace streams can be started now. {TRACE_SYS_MAX} has been exceeded.</dd>

<dt>[EINTR]</dt>

<dd>The operation was interrupted by a signal. No trace stream was created.</dd>

<dt>[EINVAL]</dt>

<dd>One or more of the trace parameters specified by the <i>attr</i> parameter is invalid.</dd>

<dt>[ENOMEM]</dt>

<dd>The implementation does not currently have sufficient memory to create the trace stream with the specified parameters.</dd>

<dt>[EPERM]</dt>

<dd>The caller does not have appropriate privilege to trace the process specified by <i>pid</i>.</dd>

<dt>[ESRCH]</dt>

<dd>The <i>pid</i> argument does not refer to an existing process.</dd>
</dl>

<p><sup>[<a href="javascript:open_code('TRL')">TRL</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
The <i>posix_trace_create_withlog</i>() function shall fail if:</p>

<dl compact>
<dt>[EBADF]</dt>

<dd>The <i>file_desc</i> argument is not a valid file descriptor open for writing.</dd>

<dt>[EINVAL]</dt>

<dd>The <i>file_desc</i> argument refers to a file with a file type that does not support the log policy associated with the trace
log.</dd>

<dt>[ENOSPC]</dt>

<dd>No space left on device. The device corresponding to the argument <i>file_desc</i> does not contain the space required to
create this trace log.</dd>
</dl>

<img src="../images/opt-end.gif" alt="[Option End]" border="0"> 

<p>The <sup>[<a href="javascript:open_code('TRL')">TRL</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border=
"0"> <i>posix_trace_flush</i>() <img src="../images/opt-end.gif" alt="[Option End]" border="0"> &nbsp;and
<i>posix_trace_shutdown</i>() functions shall fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>The value of the <i>trid</i> argument does not correspond to an active trace stream with log.</dd>

<dt>[EFBIG]</dt>

<dd>The trace log file has attempted to exceed an implementation-defined maximum file size.</dd>

<dt>[ENOSPC]</dt>

<dd>No space left on device.</dd>
</dl>

<img src="../images/opt-end.gif" alt="[Option End]" border="0"></blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_462_06"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_462_07"></a>APPLICATION USAGE</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_462_08"></a>RATIONALE</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_462_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_462_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="clock_getres.html"><i>clock_getres</i>()</a> , <a href="exec.html"><i><a href=
"../functions/exec.html">exec</a></i>()</a> , <a href="posix_trace_attr_init.html"><i>posix_trace_attr_init</i>()</a> , <a href=
"posix_trace_clear.html"><i>posix_trace_clear</i>()</a> , <a href="posix_trace_close.html"><i>posix_trace_close</i>()</a> , <a
href="posix_trace_eventid_equal.html"><i>posix_trace_eventid_equal</i>()</a> , <a href=
"posix_trace_eventtypelist_getnext_id.html"><i>posix_trace_eventtypelist_getnext_id</i>()</a> , <a href=
"posix_trace_flush.html"><i>posix_trace_flush</i>()</a> , <a href="posix_trace_get_attr.html"><i>posix_trace_get_attr</i>()</a> ,
<a href="posix_trace_get_filter.html"><i>posix_trace_get_filter</i>()</a> , <a href=
"posix_trace_get_status.html"><i>posix_trace_get_status</i>()</a> , <a href=
"posix_trace_getnext_event.html"><i>posix_trace_getnext_event</i>()</a> , <a href=
"posix_trace_open.html"><i>posix_trace_open</i>()</a> , <a href="posix_trace_set_filter.html"><i>posix_trace_set_filter</i>()</a> ,
<a href="posix_trace_shutdown.html"><i>posix_trace_shutdown</i>()</a> , <a href=
"posix_trace_start.html"><i>posix_trace_start</i>()</a> , <a href=
"posix_trace_timedgetnext_event.html"><i>posix_trace_timedgetnext_event</i>()</a> , <a href=
"posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a> , <a href=
"posix_trace_start.html"><i>posix_trace_start</i>()</a> , <a href="time.html"><i>time</i>()</a> , the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/sys/types.h.html"><i>&lt;sys/types.h&gt;</i></a>, <a href=
"../basedefs/trace.h.html"><i>&lt;trace.h&gt;</i></a></p>
</blockquote>

<h4><a name="tag_03_462_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 6. Derived from IEEE&nbsp;Std&nbsp;1003.1q-2000.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<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>