diff options
Diffstat (limited to 'static/freebsd/man9/sysctl_ctx_init.9 3.html')
| -rw-r--r-- | static/freebsd/man9/sysctl_ctx_init.9 3.html | 200 |
1 files changed, 0 insertions, 200 deletions
diff --git a/static/freebsd/man9/sysctl_ctx_init.9 3.html b/static/freebsd/man9/sysctl_ctx_init.9 3.html deleted file mode 100644 index 6d96ac48..00000000 --- a/static/freebsd/man9/sysctl_ctx_init.9 3.html +++ /dev/null @@ -1,200 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">SYSCTL_CTX_INIT(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">SYSCTL_CTX_INIT(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_ctx_init</code>, - <code class="Nm">sysctl_ctx_free</code>, - <code class="Nm">sysctl_ctx_entry_add</code>, - <code class="Nm">sysctl_ctx_entry_find</code>, - <code class="Nm">sysctl_ctx_entry_del</code> — - <span class="Nd">sysctl context for managing dynamically created sysctl - OIDs</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">int</var> - <br/> - <code class="Fn">sysctl_ctx_init</code>(<var class="Fa">struct sysctl_ctx_list - *clist</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sysctl_ctx_free</code>(<var class="Fa">struct sysctl_ctx_list - *clist</var>);</p> -<p class="Pp"><var class="Ft">struct sysctl_ctx_entry *</var> - <br/> - <code class="Fn">sysctl_ctx_entry_add</code>(<var class="Fa">struct - sysctl_ctx_list *clist</var>, <var class="Fa">struct sysctl_oid - *oidp</var>);</p> -<p class="Pp"><var class="Ft">struct sysctl_ctx_entry *</var> - <br/> - <code class="Fn">sysctl_ctx_entry_find</code>(<var class="Fa">struct - sysctl_ctx_list *clist</var>, <var class="Fa">struct sysctl_oid - *oidp</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">sysctl_ctx_entry_del</code>(<var class="Fa">struct - sysctl_ctx_list *clist</var>, <var class="Fa">struct sysctl_oid - *oidp</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 an interface for managing dynamically - created OIDs. The sysctl context is responsible for keeping track of created - OIDs, as well as their proper removal when needed. It adds a simple - transactional aspect to OID removal operations; i.e., if a removal operation - fails part way, it is possible to roll back the sysctl tree to its previous - state.</p> -<p class="Pp" id="sysctl_ctx_init">The - <a class="permalink" href="#sysctl_ctx_init"><code class="Fn">sysctl_ctx_init</code></a>() - function initializes a sysctl context. The <var class="Fa">clist</var> - argument must point to an already allocated variable. A context - <a class="permalink" href="#must"><i class="Em" id="must">must</i></a> be - initialized before use. Once it is initialized, a pointer to the context can - be passed as an argument to all the <var class="Fa">SYSCTL_ADD_*</var> - macros (see <a class="Xr">sysctl_add_oid(9)</a>), and it will be updated - with entries pointing to newly created OIDS.</p> -<p class="Pp">Internally, the context is represented as a - <a class="Xr">queue(3)</a> TAILQ linked list. The list consists of - <code class="Li">struct sysctl_ctx_entry</code> entries:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>struct sysctl_ctx_entry { - struct sysctl_oid *entry; - TAILQ_ENTRY(sysctl_ctx_entry) link; -}; - -TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry);</pre> -</div> -<p class="Pp">Each context entry points to one dynamic OID that it manages. - Newly created OIDs are always inserted in the front of the list.</p> -<p class="Pp" id="sysctl_ctx_free">The - <a class="permalink" href="#sysctl_ctx_free"><code class="Fn">sysctl_ctx_free</code></a>() - function removes the context and associated OIDs it manages. If the function - completes successfully, all managed OIDs have been unregistered (removed - from the tree) and freed, together with all their allocated memory, and the - entries of the context have been freed as well.</p> -<p class="Pp" id="sysctl_ctx_free~2">The removal operation is performed in two - steps. First, for each context entry, the function - <a class="Xr">sysctl_remove_oid(9)</a> is executed, with parameter - <var class="Fa">del</var> set to 0, which inhibits the freeing of resources. - If there are no errors during this step, - <a class="permalink" href="#sysctl_ctx_free~2"><code class="Fn">sysctl_ctx_free</code></a>() - proceeds to the next step. If the first step fails, all unregistered OIDs - associated with the context are registered again.</p> -<p class="Pp" id="Note"><a class="permalink" href="#Note"><i class="Em">Note</i></a>: - in most cases, the programmer specifies <code class="Dv">OID_AUTO</code> as - the OID number when creating an OID. However, during registration of the OID - in the tree, this number is changed to the first available number greater - than or equal to <code class="Dv">CTL_AUTO_START</code>. If the first step - of context deletion fails, re-registration of the OID does not change the - already assigned OID number (which is different from OID_AUTO). This ensures - that re-registered entries maintain their original positions in the - tree.</p> -<p class="Pp">The second step actually performs the deletion of the dynamic - OIDs. <a class="Xr">sysctl_remove_oid(9)</a> iterates through the context - list, starting from beginning (i.e., the newest entries). - <i class="Em">Important</i>: this time, the function not only deletes the - OIDs from the tree, but also frees their memory (provided that oid_refcnt == - 0), as well as the memory of all context entries.</p> -<p class="Pp" id="sysctl_ctx_entry_add">The - <a class="permalink" href="#sysctl_ctx_entry_add"><code class="Fn">sysctl_ctx_entry_add</code></a>() - function allows the addition of an existing dynamic OID to a context.</p> -<p class="Pp" id="sysctl_ctx_entry_del">The - <a class="permalink" href="#sysctl_ctx_entry_del"><code class="Fn">sysctl_ctx_entry_del</code></a>() - function removes an entry from the context. <i class="Em">Important</i>: in - this case, only the corresponding <code class="Li">struct - sysctl_ctx_entry</code> is freed, but the <var class="Fa">oidp</var> pointer - remains intact. Thereafter, the programmer is responsible for managing the - resources allocated to this OID.</p> -<p class="Pp" id="sysctl_ctx_entry_find">The - <a class="permalink" href="#sysctl_ctx_entry_find"><code class="Fn">sysctl_ctx_entry_find</code></a>() - function searches for a given <var class="Fa">oidp</var> within a context - list, either returning a pointer to the <var class="Fa">struct - sysctl_ctx_entry</var> found, or <code class="Dv">NULL</code>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="EXAMPLES"><a class="permalink" href="#EXAMPLES">EXAMPLES</a></h1> -<p class="Pp">The following is an example of how to create a new top-level - category and how to hook up another subtree to an existing static node. This - example uses contexts to keep track of the OIDs.</p> -<div class="Bd Pp Li"> -<pre>#include <sys/sysctl.h> - ... -static struct sysctl_ctx_list clist; -static struct sysctl_oid *oidp; -static int a_int; -static const char *string = "dynamic sysctl"; - ... - -sysctl_ctx_init(&clist); -oidp = SYSCTL_ADD_ROOT_NODE(&clist, - OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree"); -oidp = SYSCTL_ADD_INT(&clist, SYSCTL_CHILDREN(oidp), - OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf"); - ... -oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_debug), - OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug"); -oidp = SYSCTL_ADD_STRING(&clist, SYSCTL_CHILDREN(oidp), - OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf"); - ... -/* Now we can free up the OIDs */ -if (sysctl_ctx_free(&clist)) { - printf("can't free this context - other OIDs depend on it"); - return (ENOTEMPTY); -} else { - printf("Success!\n"); - return (0); -}</pre> -</div> -<p class="Pp">This example creates the following subtrees:</p> -<div class="Bd Pp Bd-indent Li"> -<pre>debug.newtree.newstring -newtree.newint</pre> -</div> -<p class="Pp">Note that both trees are removed, and their resources freed, - through one <code class="Fn">sysctl_ctx_free</code>() call, which starts by - freeing the newest entries (leaves) and then proceeds to free the older - entries (in this case the nodes).</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">queue(3)</a>, <a class="Xr">sysctl(8)</a>, - <a class="Xr">sysctl(9)</a>, <a class="Xr">sysctl_add_oid(9)</a>, - <a class="Xr">sysctl_remove_oid(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">The current removal algorithm is somewhat heavy. In the worst - case, all OIDs need to be unregistered, registered again, and then - unregistered and deleted. However, the algorithm does guarantee - transactional properties for removal operations.</p> -<p class="Pp">All operations on contexts involve linked list traversal. For this - reason, creation and removal of entries is relatively costly.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">July 31, 2014</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |