1<h2>etap_trace_event</h2> 2<hr> 3<p> 4<strong>System Trap</strong> - 5manipulate event probes and lock event tracing. 6<h3>SYNOPSIS</h3> 7<pre> 8<strong>#include<mach/etap.h></strong> 9 10<strong>kern_return_t etap_trace_event</strong> 11 <strong>(etap_data_t</strong> <var>mode</var>, 12 <strong>mode</strong> <var>type</var>, 13 <strong>boolean_t</strong> <var>enable</var>, 14 <strong>enable</strong> <var>nargs</var>, 15 <strong>mode</strong> <var>mode</var><strong>);</strong> 16</pre> 17<h3>PARAMETERS</h3> 18<dl> 19<p> 20<dt> <var>mode</var> 21<dd> 22indicates the desired trace flavor or reset option and may be one, 23or more, of the following: 24<ul> 25<p> 26 <li> 27ETAP_CUMULATIVE: cumulative lock event trace mode. 28 <p> 29<li> 30ETAP_MONITORED: monitored event trace mode (for probes or locks) 31<p> 32<li> 33ETAP_RESET: reset mode, clears all trace status and cumulative buffer entries 34</ul> 35<p> 36<dt> <var>type</var> 37<dd> 38used when measuring lock event contention or durations 39and may be one, or more, of the following: 40<ul> 41<p> 42 <li> 43ETAP_CONTENT 44<p> 45 <li> 46ETAP_DURATION 47</ul> 48<p> 49<dt> <var>enable</var> 50<dd> 51a boolean value indicattin whether the event trace operation is 52to be enabled (TRUE) or disabled (FALSE). 53<p> 54<dt> <var>nargs</var> 55<dd> 56specifies how many arguments are passed in the args array. 57<p> 58<dt> <var>args</var> 59<dd> 60an array, each element of which is a character string 61representing a specific subsystem or event type. These values must 62correspond to the ones the kernel uses to represent the same 63subsystems and event types. The maximum length of a character string 64is EVENT_NAME_LENGTH (defined in <strong>mach/etap.h</strong>). 65</dl> 66<h3>DESCRIPTION</h3> 67<p> 68The <strong>etap_trace_event</strong> system call is used to enable 69and disable kernel event probes (of a specified type) and all modes of lock event 70tracing. The call also supports a reset option, where the cumulative 71buffer data and all event type tracing is reset to zero. When the 72reset option is used, a new interval width can also be defined, using 73the <var>nargs</var> parameter. 74<p> 75To reset the ETAP instrumentation, 76the system call would utilize the mode parameter, passing the value of 77ETAP_RESET (All other parameters may equal NULL). If, at the time of 78reset, the <var>nargs</var> parameter is assigned a value, then the 79cumulative buffer interval width will be adjusted to be the size of 80that value. For example, the following system call would reset the 81ETAP instrumentation and adjust the cumulative buffer's interval width 82to 100ms: 83<pre> 84 etap_trace_event(ETAP_RESET, 0, 0, 100, 0); 85 86</pre> 87<h3>RETURN VALUES</h3> 88<dl> 89 <dt> <strong>KERN_SUCCESS</strong> 90 <dd> 91 The call was performed successfully. 92<p> 93 <dt> <strong>KERN_NO_SPACE</strong> 94 <dd> 95 A shortage of kernel resources prevented the operation from completing; 96 the kernel has cleaned up all residual state (the error indicates a "clean" 97 failure). 98<p> 99 <dt> <strong>KERN_FAILURE</strong> 100 <dd> 101 ETAP is not configured in the kernel. 102</dl> 103<h3>RELATED INFORMATION</h3> 104<p> 105Functions: 106<a href="etap_probe.html"><strong>etap_probe</strong></a>, 107<a href="etap_trace_thread.html"><strong>etap_trace_thread</strong></a>, 108<a href="etap_get_info.html"><strong>etap_get_info</strong></a>. 109