Files
oldlinux-files/Ref-docs/POSIX/susv3/functions/posix_trace_create.html
2024-02-19 00:21:47 -05:00

412 lines
21 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>posix_trace_create</title>
</head>
<body bgcolor="white">
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
</script>
<basefont size="3"> <a name="posix_trace_create"></a> <a name="tag_03_462"></a><!-- posix_trace_create -->
<!--header start-->
<center><font size="2">The Open Group Base Specifications Issue 6<br>
IEEE Std 1003.1-2001<br>
Copyright &copy; 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
<!--header end-->
<hr size="2" noshade>
<h4><a name="tag_03_462_01"></a>NAME</h4>
<blockquote>posix_trace_create, posix_trace_create_withlog, posix_trace_flush, posix_trace_shutdown - trace stream initialization,
flush, and shutdown from a process (<b>TRACING</b>)</blockquote>
<h4><a name="tag_03_462_02"></a>SYNOPSIS</h4>
<blockquote class="synopsis">
<div class="box"><code><tt><sup>[<a href="javascript:open_code('TRC')">TRC</a>]</sup> <img src="../images/opt-start.gif" alt=
"[Option Start]" border="0"> #include &lt;<a href="../basedefs/sys/types.h.html">sys/types.h</a>&gt;<br>
#include &lt;<a href="../basedefs/trace.h.html">trace.h</a>&gt;<br>
<br>
int posix_trace_create(pid_t</tt> <i>pid</i><tt>,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const trace_attr_t *restrict</tt> <i>attr</i><tt>,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; trace_id_t *restrict</tt> <i>trid</i><tt>);<br>
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
<div class="box"><code><tt><sup>[<a href="javascript:open_code('TRC TRL')">TRC TRL</a>]</sup> <img src="../images/opt-start.gif" alt=
"[Option Start]" border="0"> int posix_trace_create_withlog(pid_t</tt> <i>pid</i><tt>,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; const trace_attr_t *restrict</tt> <i>attr</i><tt>, int</tt> <i>file_desc</i><tt>,<br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; trace_id_t *restrict</tt> <i>trid</i><tt>);<br>
int posix_trace_flush(trace_id_t</tt> <i>trid</i><tt>);<br>
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
<div class="box"><code><tt><sup>[<a href="javascript:open_code('TRC')">TRC</a>]</sup> <img src="../images/opt-start.gif" alt=
"[Option Start]" border="0"> int posix_trace_shutdown(trace_id_t</tt> <i>trid</i><tt>); <img src="../images/opt-end.gif" alt=
"[Option End]" border="0"></tt></code></div>
<tt><br>
</tt></blockquote>
<h4><a name="tag_03_462_03"></a>DESCRIPTION</h4>
<blockquote>
<p>The <i>posix_trace_create</i>() function shall create an active trace stream. It allocates all the resources needed by the trace
stream being created for tracing the process specified by <i>pid</i> in accordance with the <i>attr</i> argument. The <i>attr</i>
argument represents the initial attributes of the trace stream and shall have been initialized by the function <a href=
"../functions/posix_trace_attr_init.html"><i>posix_trace_attr_init</i>()</a> prior to the <i>posix_trace_create</i>() call. If the
argument <i>attr</i> is NULL, the default attributes shall be used. The <i>attr</i> attributes object shall be manipulated through
a set of functions described in the <i>posix_trace_attr</i> family of functions. If the attributes of the object pointed to by
<i>attr</i> are modified later, the attributes of the trace stream shall not be affected. The <i>creation-time</i> attribute of the
newly created trace stream shall be set to the value of the system clock, if the Timers option is not supported, or to the value of
the CLOCK_REALTIME clock, if the Timers option is supported.</p>
<p>The <i>pid</i> argument represents the target process to be traced. If the process executing this function does not have
appropriate privileges to trace the process identified by <i>pid</i>, an error shall be returned. If the <i>pid</i> argument is
zero, the calling process shall be traced.</p>
<p>The <i>posix_trace_create</i>() function shall store the trace stream identifier of the new trace stream in the object pointed
to by the <i>trid</i> argument. This trace stream identifier shall be used in subsequent calls to control tracing. The <i>trid</i>
argument may only be used by the following functions:</p>
<table cellpadding="3">
<tr valign="top">
<td align="left">
<p class="tent"><br>
<a href="../functions/posix_trace_clear.html"><i>posix_trace_clear</i>()</a><br>
<a href="../functions/posix_trace_eventid_equal.html"><i>posix_trace_eventid_equal</i>()</a><br>
<a href="../functions/posix_trace_eventid_get_name.html"><i>posix_trace_eventid_get_name</i>()</a><br>
<a href="../functions/posix_trace_eventtypelist_getnext_id.html"><i>posix_trace_eventtypelist_getnext_id</i>()</a><br>
<a href="../functions/posix_trace_eventtypelist_rewind.html"><i>posix_trace_eventtypelist_rewind</i>()</a><br>
<a href="../functions/posix_trace_get_attr.html"><i>posix_trace_get_attr</i>()</a><br>
<a href="../functions/posix_trace_get_status.html"><i>posix_trace_get_status</i>()</a><br>
&nbsp;</p>
</td>
<td align="left">
<p class="tent"><br>
<a href="../functions/posix_trace_getnext_event.html"><i>posix_trace_getnext_event</i>()</a><br>
<i>posix_trace_shutdown</i>()<br>
<a href="../functions/posix_trace_start.html"><i>posix_trace_start</i>()</a><br>
<a href="../functions/posix_trace_stop.html"><i>posix_trace_stop</i>()</a><br>
<a href="../functions/posix_trace_timedgetnext_event.html"><i>posix_trace_timedgetnext_event</i>()</a><br>
<a href="../functions/posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a><br>
<a href="../functions/posix_trace_trygetnext_event.html"><i>posix_trace_trygetnext_event</i>()</a><br>
&nbsp;</p>
</td>
</tr>
</table>
<p><sup>[<a href="javascript:open_code('TEF')">TEF</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
If the Trace Event Filter option is supported, the following additional functions may use the <i>trid</i> argument:</p>
<table cellpadding="3">
<tr valign="top">
<td align="left">
<p class="tent"><a href="../functions/posix_trace_get_filter.html"><i>posix_trace_get_filter</i>()</a> &nbsp;</p>
</td>
<td align="left">
<p class="tent"><a href="../functions/posix_trace_set_filter.html"><i>posix_trace_set_filter</i>()</a> &nbsp;</p>
</td>
</tr>
</table>
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
<p>In particular, notice that the operations normally used by a trace analyzer process, such as <a href=
"../functions/posix_trace_rewind.html"><i>posix_trace_rewind</i>()</a> or <a href=
"../functions/posix_trace_close.html"><i>posix_trace_close</i>()</a>, cannot be invoked using the trace stream identifier returned
by the <i>posix_trace_create</i>() function.</p>
<p>A trace stream shall be created in a suspended state. <sup>[<a href="javascript:open_code('TEF')">TEF</a>]</sup> <img src=
"../images/opt-start.gif" alt="[Option Start]" border="0"> &nbsp;If the Trace Event Filter option is supported, its trace event
type filter shall be empty. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
<p>The <i>posix_trace_create</i>() function may be called multiple times from the same or different processes, with the system-wide
limit indicated by the runtime invariant value {TRACE_SYS_MAX}, which has the minimum value {_POSIX_TRACE_SYS_MAX}.</p>
<p>The trace stream identifier returned by the <i>posix_trace_create</i>() function in the argument pointed to by <i>trid</i> is
valid only in the process that made the function call. If it is used from another process, that is a child process, in functions
defined in IEEE&nbsp;Std&nbsp;1003.1-2001, these functions shall return with the error [EINVAL].</p>
<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 be equivalent to <i>posix_trace_create</i>(), except that it associates a
trace log with this stream. The <i>file_desc</i> argument shall be the file descriptor designating the trace log destination. The
function shall fail if this file descriptor refers to a file with a file type that is not compatible with the log policy associated
with the trace log. The list of the appropriate file types that are compatible with each log policy is implementation-defined.</p>
<p>The <i>posix_trace_create_withlog</i>() function shall return in the parameter pointed to by <i>trid</i> the trace stream
identifier, which uniquely identifies the newly created trace stream, and shall be used in subsequent calls to control tracing. The
<i>trid</i> argument may only be used by the following functions:</p>
<table cellpadding="3">
<tr valign="top">
<td align="left">
<p class="tent"><br>
<a href="../functions/posix_trace_clear.html"><i>posix_trace_clear</i>()</a><br>
<a href="../functions/posix_trace_eventid_equal.html"><i>posix_trace_eventid_equal</i>()</a><br>
<a href="../functions/posix_trace_eventid_get_name.html"><i>posix_trace_eventid_get_name</i>()</a><br>
<a href="../functions/posix_trace_eventtypelist_getnext_id.html"><i>posix_trace_eventtypelist_getnext_id</i>()</a><br>
<a href="../functions/posix_trace_eventtypelist_rewind.html"><i>posix_trace_eventtypelist_rewind</i>()</a><br>
<i>posix_trace_flush</i>()<br>
<a href="../functions/posix_trace_get_attr.html"><i>posix_trace_get_attr</i>()</a><br>
<a href="../functions/posix_trace_get_status.html"><i>posix_trace_get_status</i>()</a><br>
&nbsp;</p>
</td>
<td align="left">
<p class="tent"><br>
<a href="../functions/posix_trace_getnext_event.html"><i>posix_trace_getnext_event</i>()</a><br>
<i>posix_trace_shutdown</i>()<br>
<a href="../functions/posix_trace_start.html"><i>posix_trace_start</i>()</a><br>
<a href="../functions/posix_trace_stop.html"><i>posix_trace_stop</i>()</a><br>
<a href="../functions/posix_trace_timedgetnext_event.html"><i>posix_trace_timedgetnext_event</i>()</a><br>
<a href="../functions/posix_trace_trid_eventid_open.html"><i>posix_trace_trid_eventid_open</i>()</a><br>
<a href="../functions/posix_trace_trygetnext_event.html"><i>posix_trace_trygetnext_event</i>()</a><br>
&nbsp;</p>
</td>
</tr>
</table>
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
<p><sup>[<a href="javascript:open_code('TRL TEF')">TRL TEF</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]"
border="0"> If the Trace Event Filter option is supported, the following additional functions may use the <i>trid</i> argument:</p>
<table cellpadding="3">
<tr valign="top">
<td align="left">
<p class="tent"><a href="../functions/posix_trace_get_filter.html"><i>posix_trace_get_filter</i>()</a> &nbsp;</p>
</td>
<td align="left">
<p class="tent"><a href="../functions/posix_trace_set_filter.html"><i>posix_trace_set_filter</i>()</a> &nbsp;</p>
</td>
</tr>
</table>
<img src="../images/opt-end.gif" alt="[Option End]" border="0">
<p><sup>[<a href="javascript:open_code('TRL')">TRL</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
In particular, notice that the operations normally used by a trace analyzer process, such as <a href=
"../functions/posix_trace_rewind.html"><i>posix_trace_rewind</i>()</a> or <a href=
"../functions/posix_trace_close.html"><i>posix_trace_close</i>()</a>, cannot be invoked using the trace stream identifier returned
by the <i>posix_trace_create_withlog</i>() function.</p>
<p>The <i>posix_trace_flush</i>() function shall initiate a flush operation which copies the contents of the trace stream
identified by the argument <i>trid</i> into the trace log associated with the trace stream at the creation time. If no trace log
has been associated with the trace stream pointed to by <i>trid</i>, this function shall return an error. The termination of the
flush operation can be polled by the <a href="../functions/posix_trace_get_status.html"><i>posix_trace_get_status</i>()</a>
function. During the flush operation, it shall be possible to trace new trace events up to the point when the trace stream becomes
full. After flushing is completed, the space used by the flushed trace events shall be available for tracing new trace events.</p>
<p>If flushing the trace stream causes the resulting trace log to become full, the trace log full policy shall be applied. If the
trace <i>log-full-policy</i> attribute is set, the following occurs:</p>
<dl compact>
<dt>POSIX_TRACE_UNTIL_FULL</dt>
<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>