Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SYSCTL_CTX_INIT(9)	 BSD Kernel Developer's	Manual	    SYSCTL_CTX_INIT(9)

     sysctl_ctx_init, sysctl_ctx_free, sysctl_ctx_entry_add,
     sysctl_ctx_entry_find, sysctl_ctx_entry_del -- sysctl context for manag-
     ing dynamically created sysctl OIDs

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

     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	opera-
     tion 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 cre-
     ated 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 er-
     rors 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 num-
     ber (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 be-
     ginning (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 en-

     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 program-
     mer 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.

     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>
     static struct sysctl_ctx_list clist;
     static struct sysctl_oid *oidp;
     static int	a_int;
     static const char *string = "dynamic sysctl";

     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 {
	     return (0);

     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

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

     These functions first appeared in FreeBSD 4.2.

     Andrzej Bialecki <>

     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 rea-
     son, creation and removal of entries is relatively	costly.

BSD				 July 31, 2014				   BSD


Want to link to this manual page? Use this URL:

home | help