*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->FreeBSD man pages -> sysctl_ctx_free (9)              



NAME    [Toc]    [Back]

     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    [Toc]    [Back]

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

     sysctl_ctx_init(struct sysctl_ctx_list *clist);

     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);

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

DESCRIPTION    [Toc]    [Back]

     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

     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
     99.  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

     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    [Toc]    [Back]

     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;
     char *string = "dynamic sysctl";

     oidp = SYSCTL_ADD_NODE( &clist, SYSCTL_STATIC_CHILDREN(/* tree top */),
	     OID_AUTO, newtree, CTFLAG_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, CTFLAG_RW, 0, "new tree under debug");
     oidp = SYSCTL_ADD_STRING( &clist, SYSCTL_CHILDREN(oidp),
	     OID_AUTO, newstring, CTLFLAG_R, 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");
     } else {

     This example creates the following subtrees:


     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

SEE ALSO    [Toc]    [Back]

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

HISTORY    [Toc]    [Back]

     These functions first appeared in FreeBSD 4.2.

AUTHORS    [Toc]    [Back]

     Andrzej Bialecki <abial@FreeBSD.org>

BUGS    [Toc]    [Back]

     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.

FreeBSD 5.2.1			 July 15, 2000			 FreeBSD 5.2.1
[ Back ]
 Similar pages
Name OS Title
sysctl_add_oid FreeBSD runtime sysctl tree manipulation
SYSCTL_ADD_PROC FreeBSD runtime sysctl tree manipulation
sysctl_remove_oid FreeBSD runtime sysctl tree manipulation
SYSCTL_ADD_OID FreeBSD runtime sysctl tree manipulation
SYSCTL_ADD_NODE FreeBSD runtime sysctl tree manipulation
SYSCTL_ADD_STRING FreeBSD runtime sysctl tree manipulation
SYSCTL_ADD_INT FreeBSD runtime sysctl tree manipulation
SYSCTL_ADD_LONG FreeBSD runtime sysctl tree manipulation
SYSCTL_ADD_ULONG FreeBSD runtime sysctl tree manipulation
SYSCTL_ADD_OPAQUE FreeBSD runtime sysctl tree manipulation
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service