---
name: "sysctl_ctx_init"
section: "9"
platform: "linux"
package: "freebsd-manpages"
version: "6.0-5"
release: "Debian 4.0 (Etch)"
platforms: ["linux", "freebsd"]
url: "https://new.carta.tech/sysctl_ctx_init"
---

# sysctl\_ctx\_init(9)

sysctl context for managing dynamically created sysctl oids

## 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)](/sysctl_add_oid/9.md)), and it will be updated with entries pointing to newly created oids.

Internally, the context is represented as a [queue(3)](/queue/3.md) 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)](/sysctl_remove_oid/9.md) 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)](/sysctl_remove_oid/9.md) 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;
char *string = "dynamic sysctl";
 ...
sysctl_ctx_init(&clist);
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");
	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)](/queue/3.md), [sysctl(8)](/sysctl/8.md), [sysctl\_add\_oid(9)](/sysctl_add_oid/9.md), [sysctl\_remove\_oid(9)](/sysctl_remove_oid/9.md)

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