NAME

     sysctl_ctx_init, sysctl_ctx_free, sysctl_ctx_entry_add, sysctl_ctx_entry_find,
     sysctl_ctx_entry_del — sysctl context for managing dynamically created sysctl oids

SYNOPSIS

     #include <sys/types.h>
     #include <sys/sysctl.h>

     int
     sysctl_ctx_init(struct sysctl_ctx_list *clist);

     int
     sysctl_ctx_free(struct sysctl_ctx_list *clist);

     struct sysctl_ctx_entry *
     sysctl_ctx_entry_add(struct sysctl_ctx_list *clist, struct sysctl_oid *oidp);

     struct sysctl_ctx_entry *
     sysctl_ctx_entry_find(struct sysctl_ctx_list *clist, struct sysctl_oid *oidp);

     int
     sysctl_ctx_entry_del(struct sysctl_ctx_list *clist, struct sysctl_oid *oidp);

DESCRIPTION

     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.

     The sysctl_ctx_init() function initializes a sysctl context.  The clist argument must point
     to an already allocated variable.  A context must be initialized before use.  Once it is
     initialized, a pointer to the context can be passed as an argument to all the SYSCTL_ADD_*
     macros (see sysctl_add_oid(9)), and it will be updated with entries pointing to newly
     created oids.

     Internally, the context is represented as a queue(3) TAILQ linked list.  The list consists
     of struct sysctl_ctx_entry entries:

           struct sysctl_ctx_entry {
                   struct sysctl_oid *entry;
                   TAILQ_ENTRY(sysctl_ctx_entry) link;
           };

           TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry);

     Each context entry points to one dynamic oid that it manages.  Newly created oids are always
     inserted in the front of the list.

     The sysctl_ctx_free() 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.

     The removal operation is performed in two steps.  First, for each context entry, the
     function sysctl_remove_oid(9) is executed, with parameter del set to 0, which inhibits the
     freeing of resources.  If there are no errors during this step, sysctl_ctx_free() proceeds
     to the next step.  If the first step fails, all unregistered oids associated with the
     context are registered again.

     Note: in most cases, the programmer specifies OID_AUTO 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 CTL_AUTO_START.  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.

     The second step actually performs the deletion of the dynamic oids.  sysctl_remove_oid(9)
     iterates through the context list, starting from beginning (i.e., the newest entries).
     Important: 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.

     The sysctl_ctx_entry_add() function allows the addition of an existing dynamic oid to a
     context.

     The sysctl_ctx_entry_del() function removes an entry from the context.  Important: in this
     case, only the corresponding struct sysctl_ctx_entry is freed, but the oidp pointer remains
     intact.  Thereafter, the programmer is responsible for managing the resources allocated to
     this oid.

     The sysctl_ctx_entry_find() function searches for a given oidp within a context list, either
     returning a pointer to the struct sysctl_ctx_entry found, or NULL.

EXAMPLES

     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.

     #include <sys/sysctl.h>
      ...
     struct sysctl_ctx_list clist;
     struct sysctl_oid *oidp;
     int a_int;
     const char *string = "dynamic sysctl";
      ...

     sysctl_ctx_init(&clist);
     oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(/* tree top */),
             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);
     }

     This example creates the following subtrees:

           debug.newtree.newstring
           newtree.newint

     Note that both trees are removed, and their resources freed, through one sysctl_ctx_free()
     call, which starts by freeing the newest entries (leaves) and then proceeds to free the
     older entries (in this case the nodes).

SEE ALSO

     queue(3), sysctl(8), sysctl(9), sysctl_add_oid(9), sysctl_remove_oid(9)

HISTORY

     These functions first appeared in FreeBSD 4.2.

AUTHORS

     Andrzej Bialecki <abial@FreeBSD.org>

BUGS

     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.

     All operations on contexts involve linked list traversal.  For this reason, creation and
     removal of entries is relatively costly.