diff options
Diffstat (limited to 'static/freebsd/man9/stack.9 4.html')
| -rw-r--r-- | static/freebsd/man9/stack.9 4.html | 174 |
1 files changed, 174 insertions, 0 deletions
diff --git a/static/freebsd/man9/stack.9 4.html b/static/freebsd/man9/stack.9 4.html new file mode 100644 index 00000000..d54d5f4a --- /dev/null +++ b/static/freebsd/man9/stack.9 4.html @@ -0,0 +1,174 @@ +<table class="head"> + <tr> + <td class="head-ltitle">STACK(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">STACK(9)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">stack</code> — <span class="Nd">kernel + thread stack tracing routines</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="In">#include + <<a class="In">sys/param.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/stack.h</a>></code></p> +<p class="Pp">In the kernel configuration file: + <br/> + <code class="Cd">options DDB</code> + <br/> + <code class="Cd">options STACK</code></p> +<p class="Pp"> + <br/> + <var class="Ft">struct stack *</var> + <br/> + <code class="Fn">stack_create</code>(<var class="Fa" style="white-space: nowrap;">int + flags</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_destroy</code>(<var class="Fa" style="white-space: nowrap;">struct + stack *st</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">stack_put</code>(<var class="Fa" style="white-space: nowrap;">struct + stack *st</var>, <var class="Fa" style="white-space: nowrap;">vm_offset_t + pc</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_copy</code>(<var class="Fa" style="white-space: nowrap;">const + struct stack *src</var>, <var class="Fa" style="white-space: nowrap;">struct + stack *dst</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_zero</code>(<var class="Fa" style="white-space: nowrap;">struct + stack *st</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_print</code>(<var class="Fa" style="white-space: nowrap;">const + struct stack *st</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_print_ddb</code>(<var class="Fa" style="white-space: nowrap;">const + struct stack *st</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_print_short</code>(<var class="Fa" style="white-space: nowrap;">const + struct stack *st</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_print_short_ddb</code>(<var class="Fa" style="white-space: nowrap;">const + struct stack *st</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_sbuf_print</code>(<var class="Fa" style="white-space: nowrap;">struct + sbuf *sb</var>, <var class="Fa" style="white-space: nowrap;">const struct + stack *st</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_sbuf_print_ddb</code>(<var class="Fa" style="white-space: nowrap;">struct + sbuf *sb</var>, <var class="Fa" style="white-space: nowrap;">const struct + stack *st</var>);</p> +<p class="Pp"><var class="Ft">void</var> + <br/> + <code class="Fn">stack_save</code>(<var class="Fa" style="white-space: nowrap;">struct + stack *st</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">stack_save_td</code>(<var class="Fa" style="white-space: nowrap;">struct + stack *st</var>, <var class="Fa" style="white-space: nowrap;">struct thread + *td</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">stack</code> KPI allows querying of kernel + stack trace information and the automated generation of kernel stack trace + strings for the purposes of debugging and tracing. To use the KPI, at least + one of <code class="Cd">options DDB</code> and <code class="Cd">options + STACK</code> must be compiled into the kernel.</p> +<p class="Pp" id="stack_zero">Each stack trace is described by a + <var class="Vt">struct stack</var>. It can be declared in the usual ways, + including on the stack, and optionally initialized with + <a class="permalink" href="#stack_zero"><code class="Fn">stack_zero</code></a>(), + though this is not necessary before saving a trace. It can also be + dynamically allocated with + <a class="permalink" href="#stack_create"><code class="Fn" id="stack_create">stack_create</code></a>(). + The <var class="Ar">flags</var> argument is passed to + <a class="Xr">malloc(9)</a>. This dynamic allocation must be freed with + <a class="permalink" href="#stack_destroy"><code class="Fn" id="stack_destroy">stack_destroy</code></a>().</p> +<p class="Pp" id="stack_save">A trace of the current thread's kernel call stack + may be captured using + <a class="permalink" href="#stack_save"><code class="Fn">stack_save</code></a>(). + <a class="permalink" href="#stack_save_td"><code class="Fn" id="stack_save_td">stack_save_td</code></a>() + can be used to capture the kernel stack of a caller-specified thread. + Callers of <code class="Fn">stack_save_td</code>() must own the thread lock + of the specified thread, and the thread's stack must not be swapped out. + <code class="Fn">stack_save_td</code>() can capture the kernel stack of a + running thread, though note that this is not implemented on all platforms. + If the thread is running, the caller must also hold the process lock for the + target thread.</p> +<p class="Pp" id="stack_print"><a class="permalink" href="#stack_print"><code class="Fn">stack_print</code></a>() + and + <a class="permalink" href="#stack_print_short"><code class="Fn" id="stack_print_short">stack_print_short</code></a>() + may be used to print a stack trace using the kernel + <a class="Xr">printf(9)</a>, and may sleep as a result of acquiring + <a class="Xr">sx(9)</a> locks in the kernel linker while looking up symbol + names. In locking-sensitive environments, the unsynchronized + <a class="permalink" href="#stack_print_ddb"><code class="Fn" id="stack_print_ddb">stack_print_ddb</code></a>() + and + <a class="permalink" href="#stack_print_short_ddb"><code class="Fn" id="stack_print_short_ddb">stack_print_short_ddb</code></a>() + variants may be invoked. This function bypasses kernel linker locking, + making it usable in <a class="Xr">ddb(4)</a>, but not in a live system where + linker data structures may change.</p> +<p class="Pp" id="stack_sbuf_print"><a class="permalink" href="#stack_sbuf_print"><code class="Fn">stack_sbuf_print</code></a>() + may be used to construct a human-readable string, including conversion + (where possible) from a simple kernel instruction pointer to a named symbol + and offset. The argument <var class="Ar">sb</var> must be an initialized + <code class="Dv">struct sbuf</code> as described in + <a class="Xr">sbuf(9)</a>. This function may sleep if an auto-extending + <code class="Dv">struct sbuf</code> is used, or due to kernel linker + locking. In locking-sensitive environments, such as + <a class="Xr">ddb(4)</a>, the unsynchronized + <a class="permalink" href="#stack_sbuf_print_ddb"><code class="Fn" id="stack_sbuf_print_ddb">stack_sbuf_print_ddb</code></a>() + variant may be invoked to avoid kernel linker locking; it should be used + with a fixed-length sbuf.</p> +<p class="Pp">The utility functions <code class="Nm">stack_zero</code>, + <code class="Nm">stack_copy</code>, and <code class="Nm">stack_put</code> + may be used to manipulate stack data structures directly.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN + VALUES</a></h1> +<p class="Pp"><code class="Fn">stack_put</code>() returns 0 on success. + Otherwise the <code class="Dv">struct stack</code> does not contain space to + record additional frames, and a non-zero value is returned.</p> +<p class="Pp"><code class="Fn">stack_save_td</code>() returns 0 when the stack + capture was successful and a non-zero error number otherwise. In particular, + <code class="Er">EBUSY</code> is returned if the thread was running in user + mode at the time that the capture was attempted, and + <code class="Er">EOPNOTSUPP</code> is returned if the operation is not + implemented.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">ddb(4)</a>, <a class="Xr">printf(9)</a>, + <a class="Xr">sbuf(9)</a>, <a class="Xr">sx(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">The <code class="Nm">stack</code> function suite was created by + <span class="An">Antoine Brodin</span>. <code class="Nm">stack</code> was + extended by <span class="An">Robert Watson</span> for general-purpose use + outside of <a class="Xr">ddb(4)</a>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 6, 2022</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |