diff options
author | hselasky <hselasky@FreeBSD.org> | 2014-07-31 17:18:40 +0000 |
---|---|---|
committer | hselasky <hselasky@FreeBSD.org> | 2014-07-31 17:18:40 +0000 |
commit | 8bdfc1896d7dd079283b90589f3992dd9bfd3843 (patch) | |
tree | ddc74ec9e353b85611a3bd221e9539a960ba044e /share/man/man9/sysctl_ctx_init.9 | |
parent | 247a87cdab0fe70a30c73e81d5d634f5366f3c1e (diff) | |
download | FreeBSD-src-8bdfc1896d7dd079283b90589f3992dd9bfd3843.zip FreeBSD-src-8bdfc1896d7dd079283b90589f3992dd9bfd3843.tar.gz |
- Updated SYSCTL manual pages after recent changes to the kernel
SYSCTL code. Added description of new macros and functions.
- Merged dynamic and static SYSCTL related content into a single
manual page, hence parameters and functionality is very much the same.
- Uppercased all occurrences of "OID".
- Updated all SYSCTL examples.
PR: 192101
Diffstat (limited to 'share/man/man9/sysctl_ctx_init.9')
-rw-r--r-- | share/man/man9/sysctl_ctx_init.9 | 54 |
1 files changed, 27 insertions, 27 deletions
diff --git a/share/man/man9/sysctl_ctx_init.9 b/share/man/man9/sysctl_ctx_init.9 index b3c0d3b..28c7b93 100644 --- a/share/man/man9/sysctl_ctx_init.9 +++ b/share/man/man9/sysctl_ctx_init.9 @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd July 15, 2000 +.Dd July 31, 2014 .Dt SYSCTL_CTX_INIT 9 .Os .Sh NAME @@ -36,7 +36,7 @@ .Nm sysctl_ctx_entry_add , .Nm sysctl_ctx_entry_find , .Nm sysctl_ctx_entry_del -.Nd "sysctl context for managing dynamically created sysctl oids" +.Nd "sysctl context for managing dynamically created sysctl OIDs" .Sh SYNOPSIS .In sys/types.h .In sys/sysctl.h @@ -65,10 +65,10 @@ .Fc .Sh DESCRIPTION These functions provide an interface -for managing dynamically created oids. -The sysctl context is responsible for keeping track of created oids, +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; +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. @@ -87,7 +87,7 @@ a pointer to the context can be passed as an argument to all the .Fa SYSCTL_ADD_* macros (see .Xr sysctl_add_oid 9 ) , -and it will be updated with entries pointing to newly created oids. +and it will be updated with entries pointing to newly created OIDS. .Pp Internally, the context is represented as a .Xr queue 3 @@ -104,14 +104,14 @@ struct sysctl_ctx_entry { TAILQ_HEAD(sysctl_ctx_list, sysctl_ctx_entry); .Ed .Pp -Each context entry points to one dynamic oid that it manages. -Newly created oids are always inserted in the front of the list. +Each context entry points to one dynamic OID that it manages. +Newly created OIDs are always inserted in the front of the list. .Pp The .Fn sysctl_ctx_free -function removes the context and associated oids it manages. +function removes the context and associated OIDs it manages. If the function completes successfully, -all managed oids have been unregistered +all managed OIDs have been unregistered (removed from the tree) and freed, together with all their allocated memory, @@ -127,34 +127,34 @@ If there are no errors during this step, .Fn sysctl_ctx_free proceeds to the next step. If the first step fails, -all unregistered oids associated with the context are registered again. +all unregistered OIDs associated with the context are registered again. .Pp .Em Note : in most cases, the programmer specifies .Dv OID_AUTO -as the oid number when creating an oid. -However, during registration of the oid in the tree, +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 .Dv CTL_AUTO_START . If the first step of context deletion fails, -re-registration of the oid does not change the already assigned oid number +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. .Pp -The second step actually performs the deletion of the dynamic oids. +The second step actually performs the deletion of the dynamic OIDs. .Xr sysctl_remove_oid 9 iterates through the context list, starting from beginning (i.e., the newest entries). .Em Important : -this time, the function not only deletes the oids from the tree, +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. .Pp The .Fn sysctl_ctx_entry_add -function allows the addition of an existing dynamic oid to a context. +function allows the addition of an existing dynamic OID to a context. .Pp The .Fn sysctl_ctx_entry_del @@ -166,7 +166,7 @@ is freed, but the .Fa oidp pointer remains intact. Thereafter, the programmer is responsible for managing the resources -allocated to this oid. +allocated to this OID. .Pp The .Fn sysctl_ctx_entry_find @@ -181,18 +181,18 @@ or .Sh 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. +This example uses contexts to keep track of the OIDs. .Bd -literal #include <sys/sysctl.h> ... -struct sysctl_ctx_list clist; -struct sysctl_oid *oidp; -int a_int; -const char *string = "dynamic sysctl"; +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_NODE(&clist, SYSCTL_STATIC_CHILDREN(/* tree top */), +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"); @@ -202,9 +202,9 @@ oidp = SYSCTL_ADD_NODE(&clist, SYSCTL_STATIC_CHILDREN(_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 */ +/* Now we can free up the OIDs */ if (sysctl_ctx_free(&clist)) { - printf("can't free this context - other oids depend on it"); + printf("can't free this context - other OIDs depend on it"); return (ENOTEMPTY); } else { printf("Success!\\n"); @@ -237,7 +237,7 @@ These functions first appeared in .Sh BUGS The current removal algorithm is somewhat heavy. In the worst case, -all oids need to be unregistered, registered again, +all OIDs need to be unregistered, registered again, and then unregistered and deleted. However, the algorithm does guarantee transactional properties for removal operations. |