diff options
Diffstat (limited to 'static/freebsd/man9/sysctl_add_oid.9 3.html')
| -rw-r--r-- | static/freebsd/man9/sysctl_add_oid.9 3.html | 151 |
1 files changed, 151 insertions, 0 deletions
diff --git a/static/freebsd/man9/sysctl_add_oid.9 3.html b/static/freebsd/man9/sysctl_add_oid.9 3.html new file mode 100644 index 00000000..a47cb3ce --- /dev/null +++ b/static/freebsd/man9/sysctl_add_oid.9 3.html @@ -0,0 +1,151 @@ +<table class="head"> + <tr> + <td class="head-ltitle">SYSCTL_ADD_OID(9)</td> + <td class="head-vol">Kernel Developer's Manual</td> + <td class="head-rtitle">SYSCTL_ADD_OID(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">sysctl_add_oid</code>, + <code class="Nm">sysctl_move_oid</code>, + <code class="Nm">sysctl_remove_oid</code>, + <code class="Nm">sysctl_remove_name</code> — <span class="Nd">runtime + sysctl tree manipulation</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/types.h</a>></code> + <br/> + <code class="In">#include <<a class="In">sys/sysctl.h</a>></code></p> +<p class="Pp"><var class="Ft">struct sysctl_oid *</var> + <br/> + <code class="Fn">sysctl_add_oid</code>(<var class="Fa">struct sysctl_ctx_list + *ctx</var>, <var class="Fa">struct sysctl_oid_list *parent</var>, + <var class="Fa">int number</var>, <var class="Fa">const char *name</var>, + <var class="Fa">int kind</var>, <var class="Fa">void *arg1</var>, + <var class="Fa">intmax_t arg2</var>, <var class="Fa">int (*handler) + (SYSCTL_HANDLER_ARGS)</var>, <var class="Fa">const char *format</var>, + <var class="Fa">const char *descr</var>, <var class="Fa">const char + *label</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sysctl_move_oid</code>(<var class="Fa">struct sysctl_oid + *oidp</var>, <var class="Fa">struct sysctl_oid_list *parent</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sysctl_remove_oid</code>(<var class="Fa">struct sysctl_oid + *oidp</var>, <var class="Fa">int del</var>, <var class="Fa">int + recurse</var>);</p> +<p class="Pp"><var class="Ft">int</var> + <br/> + <code class="Fn">sysctl_remove_name</code>(<var class="Fa">struct sysctl_oid + *oidp</var>, <var class="Fa">const char *name</var>, <var class="Fa">int + del</var>, <var class="Fa">int recurse</var>);</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">These functions provide the interface for creating and deleting + sysctl OIDs at runtime for example during the lifetime of a module. The + wrapper macros defined by <a class="Xr">sysctl(9)</a> are recommended when + creating new OIDs. + <a class="permalink" href="#sysctl_add_oid"><code class="Fn" id="sysctl_add_oid">sysctl_add_oid</code></a>() + should not be called directly from the code.</p> +<p class="Pp">Dynamic OIDs of type <code class="Dv">CTLTYPE_NODE</code> are + reusable so that several code sections can create and delete them, but in + reality they are allocated and freed based on their reference count. As a + consequence, it is possible for two or more code sections to create + partially overlapping trees that they both can use. It is not possible to + create overlapping leaves, nor to create different child types with the same + name and parent.</p> +<p class="Pp" id="sysctl_add_oid~2">The + <a class="permalink" href="#sysctl_add_oid~2"><code class="Fn">sysctl_add_oid</code></a>() + function creates a raw OID of any type and connects it to its parent node, + if any. If the OID is successfully created, the function returns a pointer + to it else it returns <code class="Dv">NULL</code>. Many of the arguments + for <code class="Fn">sysctl_add_oid</code>() are common to the wrapper + macros defined by <a class="Xr">sysctl(9)</a>.</p> +<p class="Pp" id="sysctl_move_oid">The + <a class="permalink" href="#sysctl_move_oid"><code class="Fn">sysctl_move_oid</code></a>() + function reparents an existing OID. The OID is assigned a new number as if + it had been created with <var class="Fa">number</var> set to + <code class="Dv">OID_AUTO</code>.</p> +<p class="Pp" id="sysctl_remove_oid">The + <a class="permalink" href="#sysctl_remove_oid"><code class="Fn">sysctl_remove_oid</code></a>() + function removes a dynamically created OID from the tree and optionally + freeing its resources. It takes the following arguments:</p> +<dl class="Bl-tag"> + <dt><var class="Fa">oidp</var></dt> + <dd>A pointer to the dynamic OID to be removed. If the OID is not dynamic, or + the pointer is <code class="Dv">NULL</code>, the function returns + <code class="Er">EINVAL</code>.</dd> + <dt><var class="Fa">del</var></dt> + <dd>If non-zero, <code class="Fn">sysctl_remove_oid</code>() will try to free + the OID's resources when the reference count of the OID becomes zero. + However, if <var class="Fa">del</var> is set to 0, the routine will only + deregister the OID from the tree, without freeing its resources. This + behaviour is useful when the caller expects to rollback (possibly + partially failed) deletion of many OIDs later.</dd> + <dt id="WARNING"><var class="Fa">recurse</var></dt> + <dd>If non-zero, attempt to remove the node and all its children. If + <span class="Pa">recurse</span> is set to 0, any attempt to remove a node + that contains any children will result in a + <code class="Er">ENOTEMPTY</code> error. + <a class="permalink" href="#WARNING"><i class="Em">WARNING</i></a>: + <a class="permalink" href="#use"><i class="Em" id="use">use recursive + deletion with extreme caution</i></a>! Normally it should not be needed if + contexts are used. Contexts take care of tracking inter-dependencies + between users of the tree. However, in some extreme cases it might be + necessary to remove part of the subtree no matter how it was created, in + order to free some other resources. Be aware, though, that this may result + in a system <a class="Xr">panic(9)</a> if other code sections continue to + use removed subtrees.</dd> +</dl> +<p class="Pp" id="sysctl_remove_name">The + <a class="permalink" href="#sysctl_remove_name"><code class="Fn">sysctl_remove_name</code></a>() + function looks up the child node matching the <var class="Fa">name</var> + argument and then invokes the <code class="Fn">sysctl_remove_oid</code>() + function on that node, passing along the <var class="Fa">del</var> and + <var class="Fa">recurse</var> arguments. If a node having the specified name + does not exist an error code of <code class="Er">ENOENT</code> is returned. + Else the error code from <code class="Fn">sysctl_remove_oid</code>() is + returned.</p> +<p class="Pp">In most cases the programmer should use contexts, as described in + <a class="Xr">sysctl_ctx_init(9)</a>, to keep track of created OIDs, and to + delete them later in orderly fashion.</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">sysctl(8)</a>, <a class="Xr">sysctl(9)</a>, + <a class="Xr">sysctl_ctx_free(9)</a>, + <a class="Xr">sysctl_ctx_init(9)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> +<p class="Pp">These functions first appeared in <span class="Ux">FreeBSD + 4.2</span>.</p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp"><span class="An">Andrzej Bialecki</span> + <<a class="Mt" href="mailto:abial@FreeBSD.org">abial@FreeBSD.org</a>></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> +<p class="Pp">Sharing nodes between many code sections causes interdependencies + that sometimes may lock the resources. For example, if module A hooks up a + subtree to an OID created by module B, module B will be unable to delete + that OID. These issues are handled properly by sysctl contexts.</p> +<p class="Pp">Many operations on the tree involve traversing linked lists. For + this reason, OID creation and removal is relatively costly.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">December 13, 2016</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |