Differential D8775 Diff 22888 share/man/man9/sysctl.9

Changeset View

Standalone View

share/man/man9/sysctl.9

	Show All 19 Lines
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd October 23, 2015			.Dd December 13, 2016
				rpokalaUnsubmitted Done Inline Actions s/2015/2016/ # or maybe 2017 by the time this gets committed ;-) rpokala: s/2015/2016/ # or maybe 2017 by the time this gets committed ;-)
	.Dt SYSCTL 9			.Dt SYSCTL 9
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm SYSCTL_DECL ,			.Nm SYSCTL_DECL ,
	.Nm SYSCTL_ADD_INT ,			.Nm SYSCTL_ADD_INT ,
	.Nm SYSCTL_ADD_LONG ,			.Nm SYSCTL_ADD_LONG ,
	.Nm SYSCTL_ADD_NODE ,			.Nm SYSCTL_ADD_NODE ,
				.Nm SYSCTL_ADD_NODE_WITH_LABEL ,
	.Nm SYSCTL_ADD_OPAQUE ,			.Nm SYSCTL_ADD_OPAQUE ,
	.Nm SYSCTL_ADD_PROC ,			.Nm SYSCTL_ADD_PROC ,
	.Nm SYSCTL_ADD_QUAD ,			.Nm SYSCTL_ADD_QUAD ,
	.Nm SYSCTL_ADD_ROOT_NODE ,			.Nm SYSCTL_ADD_ROOT_NODE ,
	.Nm SYSCTL_ADD_S8 ,			.Nm SYSCTL_ADD_S8 ,
	.Nm SYSCTL_ADD_S16 ,			.Nm SYSCTL_ADD_S16 ,
	.Nm SYSCTL_ADD_S32 ,			.Nm SYSCTL_ADD_S32 ,
	.Nm SYSCTL_ADD_S64 ,			.Nm SYSCTL_ADD_S64 ,
	.Nm SYSCTL_ADD_STRING ,			.Nm SYSCTL_ADD_STRING ,
	.Nm SYSCTL_ADD_STRUCT ,			.Nm SYSCTL_ADD_STRUCT ,
	.Nm SYSCTL_ADD_U8 ,			.Nm SYSCTL_ADD_U8 ,
	.Nm SYSCTL_ADD_U16 ,			.Nm SYSCTL_ADD_U16 ,
	.Nm SYSCTL_ADD_U32 ,			.Nm SYSCTL_ADD_U32 ,
	.Nm SYSCTL_ADD_U64 ,			.Nm SYSCTL_ADD_U64 ,
	.Nm SYSCTL_ADD_UAUTO ,			.Nm SYSCTL_ADD_UAUTO ,
	.Nm SYSCTL_ADD_UINT ,			.Nm SYSCTL_ADD_UINT ,
	.Nm SYSCTL_ADD_ULONG ,			.Nm SYSCTL_ADD_ULONG ,
	.Nm SYSCTL_ADD_UQUAD ,			.Nm SYSCTL_ADD_UQUAD ,
	.Nm SYSCTL_CHILDREN ,			.Nm SYSCTL_CHILDREN ,
	.Nm SYSCTL_STATIC_CHILDREN ,			.Nm SYSCTL_STATIC_CHILDREN ,
	.Nm SYSCTL_NODE_CHILDREN ,			.Nm SYSCTL_NODE_CHILDREN ,
	.Nm SYSCTL_PARENT ,			.Nm SYSCTL_PARENT ,
	.Nm SYSCTL_INT ,			.Nm SYSCTL_INT ,
				.Nm SYSCTL_INT_WITH_LABEL ,
	.Nm SYSCTL_LONG ,			.Nm SYSCTL_LONG ,
	.Nm SYSCTL_NODE ,			.Nm SYSCTL_NODE ,
				.Nm SYSCTL_NODE_WITH_LABEL ,
	.Nm SYSCTL_OPAQUE ,			.Nm SYSCTL_OPAQUE ,
	.Nm SYSCTL_PROC ,			.Nm SYSCTL_PROC ,
	.Nm SYSCTL_QUAD ,			.Nm SYSCTL_QUAD ,
	.Nm SYSCTL_ROOT_NODE ,			.Nm SYSCTL_ROOT_NODE ,
	.Nm SYSCTL_S8 ,			.Nm SYSCTL_S8 ,
	.Nm SYSCTL_S16 ,			.Nm SYSCTL_S16 ,
	.Nm SYSCTL_S32 ,			.Nm SYSCTL_S32 ,
	.Nm SYSCTL_S64 ,			.Nm SYSCTL_S64 ,
	Show All 38 Lines
	.Fa "struct sysctl_oid_list *parent"			.Fa "struct sysctl_oid_list *parent"
	.Fa "int number"			.Fa "int number"
	.Fa "const char *name"			.Fa "const char *name"
	.Fa "int ctlflags"			.Fa "int ctlflags"
	.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"			.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
	.Fa "const char *descr"			.Fa "const char *descr"
	.Fc			.Fc
	.Ft struct sysctl_oid *			.Ft struct sysctl_oid *
				.Fo SYSCTL_ADD_NODE_WITH_LABEL
				.Fa "struct sysctl_ctx_list *ctx"
				.Fa "struct sysctl_oid_list *parent"
				.Fa "int number"
				.Fa "const char *name"
				.Fa "int ctlflags"
				.Fa "int (*handler)(SYSCTL_HANDLER_ARGS)"
				.Fa "const char *descr"
				.Fa "const char *label"
				.Fc
				.Ft struct sysctl_oid *
	.Fo SYSCTL_ADD_OPAQUE			.Fo SYSCTL_ADD_OPAQUE
	.Fa "struct sysctl_ctx_list *ctx"			.Fa "struct sysctl_ctx_list *ctx"
	.Fa "struct sysctl_oid_list *parent"			.Fa "struct sysctl_oid_list *parent"
	.Fa "int number"			.Fa "int number"
	.Fa "const char *name"			.Fa "const char *name"
	.Fa "int ctlflags"			.Fa "int ctlflags"
	.Fa "void *ptr"			.Fa "void *ptr"
	.Fa "intptr_t len"			.Fa "intptr_t len"
	▲ Show 20 Lines • Show All 196 Lines • ▼ Show 20 Lines
	.Fa "parent"			.Fa "parent"
	.Fa "name"			.Fa "name"
	.Fc			.Fc
	.Ft struct sysctl_oid *			.Ft struct sysctl_oid *
	.Fo SYSCTL_PARENT			.Fo SYSCTL_PARENT
	.Fa "struct sysctl_oid *oid"			.Fa "struct sysctl_oid *oid"
	.Fc			.Fc
	.Fn SYSCTL_INT parent number name ctlflags ptr val descr			.Fn SYSCTL_INT parent number name ctlflags ptr val descr
				.Fn SYSCTL_INT_WITH_LABEL parent number name ctlflags ptr val descr label
	.Fn SYSCTL_LONG parent number name ctlflags ptr val descr			.Fn SYSCTL_LONG parent number name ctlflags ptr val descr
	.Fn SYSCTL_NODE parent number name ctlflags handler descr			.Fn SYSCTL_NODE parent number name ctlflags handler descr
				.Fn SYSCTL_NODE_WITH_LABEL parent number name ctlflags handler descr label
	.Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr			.Fn SYSCTL_OPAQUE parent number name ctlflags ptr len format descr
	.Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr			.Fn SYSCTL_PROC parent number name ctlflags arg1 arg2 handler format descr
	.Fn SYSCTL_QUAD parent number name ctlflags ptr val descr			.Fn SYSCTL_QUAD parent number name ctlflags ptr val descr
	.Fn SYSCTL_ROOT_NODE number name ctlflags handler descr			.Fn SYSCTL_ROOT_NODE number name ctlflags handler descr
	.Fn SYSCTL_S8 parent number name ctlflags ptr val descr			.Fn SYSCTL_S8 parent number name ctlflags ptr val descr
	.Fn SYSCTL_S16 parent number name ctlflags ptr val descr			.Fn SYSCTL_S16 parent number name ctlflags ptr val descr
	.Fn SYSCTL_S32 parent number name ctlflags ptr val descr			.Fn SYSCTL_S32 parent number name ctlflags ptr val descr
	.Fn SYSCTL_S64 parent number name ctlflags ptr val descr			.Fn SYSCTL_S64 parent number name ctlflags ptr val descr
	▲ Show 20 Lines • Show All 117 Lines • ▼ Show 20 Lines
	.It Cm QU			.It Cm QU
	.Li "u_quad_t"			.Li "u_quad_t"
	.It Cm "S,TYPE"			.It Cm "S,TYPE"
	.Li "struct TYPE"			.Li "struct TYPE"
	structures			structures
	.El			.El
	.It Fa descr			.It Fa descr
	A pointer to a textual description of the OID.			A pointer to a textual description of the OID.
				.It Fa label
				A pointer to an aggregation label for this component of the OID.
				To make it easier to export sysctl data to monitoring systems that
				support aggregations through labels (e.g., Prometheus),
				this argument can be used to attach a label name to an OID.
				The label acts as a hint that this component's name should not be part
				of the metric's name,
				but attached to the metric as a label instead.
				.Pp
				Labels should only be applied to siblings that are structurally similar
				and encode the same type of value,
				as aggregation is of no use otherwise.
	.El			.El
	.Sh CREATING ROOT NODES			.Sh CREATING ROOT NODES
	Sysctl MIBs or OIDs are created in a hierarchical tree.			Sysctl MIBs or OIDs are created in a hierarchical tree.
	The nodes at the bottom of the tree are called root nodes, and have no			The nodes at the bottom of the tree are called root nodes, and have no
	parent OID.			parent OID.
	To create bottom tree nodes the			To create bottom tree nodes the
	.Fn SYSCTL_ROOT_NODE			.Fn SYSCTL_ROOT_NODE
	macro or the			macro or the
	▲ Show 20 Lines • Show All 42 Lines • ▼ Show 20 Lines
	function.			function.
	The handler is responsible for handling all read and write requests to			The handler is responsible for handling all read and write requests to
	the OID.			the OID.
	This OID type is especially useful if the kernel data is not easily			This OID type is especially useful if the kernel data is not easily
	accessible, or needs to be processed before exporting.			accessible, or needs to be processed before exporting.
	.Sh CREATING A STATIC SYSCTL			.Sh CREATING A STATIC SYSCTL
	Static sysctls are declared using one of the			Static sysctls are declared using one of the
	.Fn SYSCTL_INT ,			.Fn SYSCTL_INT ,
				.Fn SYSCTL_INT_WITH_LABEL ,
	.Fn SYSCTL_LONG ,			.Fn SYSCTL_LONG ,
	.Fn SYSCTL_NODE ,			.Fn SYSCTL_NODE ,
				.Fn SYSCTL_NODE_WITH_LABEL ,
	.Fn SYSCTL_OPAQUE ,			.Fn SYSCTL_OPAQUE ,
	.Fn SYSCTL_PROC ,			.Fn SYSCTL_PROC ,
	.Fn SYSCTL_QUAD ,			.Fn SYSCTL_QUAD ,
	.Fn SYSCTL_ROOT_NODE ,			.Fn SYSCTL_ROOT_NODE ,
	.Fn SYSCTL_S8 ,			.Fn SYSCTL_S8 ,
	.Fn SYSCTL_S16 ,			.Fn SYSCTL_S16 ,
	.Fn SYSCTL_S32 ,			.Fn SYSCTL_S32 ,
	.Fn SYSCTL_S64 ,			.Fn SYSCTL_S64 ,
	.Fn SYSCTL_STRING ,			.Fn SYSCTL_STRING ,
	.Fn SYSCTL_STRUCT ,			.Fn SYSCTL_STRUCT ,
	.Fn SYSCTL_U8 ,			.Fn SYSCTL_U8 ,
	.Fn SYSCTL_U16 ,			.Fn SYSCTL_U16 ,
	.Fn SYSCTL_U32 ,			.Fn SYSCTL_U32 ,
	.Fn SYSCTL_U64 ,			.Fn SYSCTL_U64 ,
	.Fn SYSCTL_UINT ,			.Fn SYSCTL_UINT ,
	.Fn SYSCTL_ULONG			.Fn SYSCTL_ULONG
	or			or
	.Fn SYSCTL_UQUAD			.Fn SYSCTL_UQUAD
	macros.			macros.
	.Sh CREATING A DYNAMIC SYSCTL			.Sh CREATING A DYNAMIC SYSCTL
	Dynamic nodes are created using one of the			Dynamic nodes are created using one of the
	.Fn SYSCTL_ADD_INT ,			.Fn SYSCTL_ADD_INT ,
	.Fn SYSCTL_ADD_LONG ,			.Fn SYSCTL_ADD_LONG ,
	.Fn SYSCTL_ADD_NODE ,			.Fn SYSCTL_ADD_NODE ,
				.Fn SYSCTL_ADD_NODE_WITH_LABEL ,
	.Fn SYSCTL_ADD_OPAQUE ,			.Fn SYSCTL_ADD_OPAQUE ,
	.Fn SYSCTL_ADD_PROC ,			.Fn SYSCTL_ADD_PROC ,
	.Fn SYSCTL_ADD_QUAD ,			.Fn SYSCTL_ADD_QUAD ,
	.Fn SYSCTL_ADD_ROOT_NODE ,			.Fn SYSCTL_ADD_ROOT_NODE ,
	.Fn SYSCTL_ADD_S8 ,			.Fn SYSCTL_ADD_S8 ,
	.Fn SYSCTL_ADD_S16 ,			.Fn SYSCTL_ADD_S16 ,
	.Fn SYSCTL_ADD_S32 ,			.Fn SYSCTL_ADD_S32 ,
	.Fn SYSCTL_ADD_S64 ,			.Fn SYSCTL_ADD_S64 ,
	▲ Show 20 Lines • Show All 301 Lines • Show Last 20 Lines