Differential D18696 Diff 52443 lib/libsysctl/libsysctl.3

Changeset View

Standalone View

lib/libsysctl/libsysctl.3

Property	Old Value	New Value
svn:eol-style	null	native \ No newline at end of property
svn:keywords	null	FreeBSD=%H \ No newline at end of property
svn:mime-type	null	text/plain \ No newline at end of property

				.\"
				.\" Copyright (c) 2018 Alfonso S. Siciliano
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice, this list of conditions and the following disclaimer in the
				.\" documentation and/or other materials provided with the distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
				.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
				.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
				.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
				.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
				.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
				.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
				.\" 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
				.\" SUCH DAMAGE.
				.\"
				.Dd November 26, 2018
				.Dt LIBSYSCTL 3
				.Os
				.Sh NAME
				.Nm LIBSYSCTL_IDMAXLEN,
				.Nm libsysctl_nametoid,
				.Nm libsysctl_name,
				.Nm LIBSYSCTL_NAMELEN,
				.Nm libsysctl_desc,
				.Nm LIBSYSCTL_DESCLEN,
				.Nm libsysctl_label,
				.Nm LIBSYSCTL_LABELLEN,
				.Nm libsysctl_info,
				.Nm LIBSYSCTL_IKIND,
				.Nm LIBSYSCTL_ITYPE,
				.Nm LIBSYSCTL_IFLAGS,
				.Nm LIBSYSCTL_IFMT,
				.Nm libsysctl_nextnode,
				.Nm libsysctl_nextleaf,
				.Nm libsysctl_object,
				.Nm libsysctl_freeobject,
				.Nm libsysctl_filterlist,
				.Nm LIBSYSCTL_LIST,
				.Nm libsysctl_grouplist,
				.Nm libsysctl_freelist,
				.Nm libsysctl_tree,
				.Nm libsysctl_freetree,
				.Nm LIBSYSCTL_GETVALUE,
				.Nm LIBSYSCTL_SETVALUE,
				.Nm LIBSYSCTL_OLDNEWVALUE,
				.Nd manage sysctl-tree in userpace
				.Sh LIBRARY
				.Lb libsysctl
				.Sh SYNOPSIS
				.In sys/types.h
				.In sys/queue.h
				.In libsysctl.h
				.Vt LIBSYSCTL_IDMAXLEN;
				.Ft "int"
				.Fn libsysctl_nametoid "const char name" "size_t namelen" "int id" "size_t* idlen"
				.Ft "int"
				.Fn libsysctl_name "int id" "size_t idlen" "char name" "size_t *namelen"
				.Fn LIBSYSCTL_NAMELEN "int id" "size_t idlen" "size_t namelen"
				.Ft "int"
				.Fn libsysctl_desc "int id" "size_t idlen" "char desc" "size_t *desclen"
				.Fn LIBSYSCTL_DESCLEN "int id" "size_t idlen" "size_t desclen"
				.Ft "int"
				.Fn libsysctl_label "int id" "size_t idlen" "char label" "size_t *labellen"
				.Fn LIBSYSCTL_LABELLEN "int id" "size_t idlen" "size_t labellen"
				.Ft "int"
				.Fn libsysctl_info "int id" "size_t idlen" "void info" "size_t *infolen"
				.Ft "uint32_t"
				.Fn LIBSYSCTL_IKIND "info"
				.Ft "uint8_t"
				.Fn LIBSYSCTL_ITYPE "info"
				.Ft "uint32_t"
				.Fn LIBSYSCTL_IFLAGS "info"
				.Ft "char *"
				.Fn LIBSYSCTL_IFMT "info"
				.Ft "int"
				.Fn libsysctl_nextleaf "int id" "size_t idlen" "int nextid" "size_t *nextidlen"
				.Ft "int"
				.Fn libsysctl_nextnode "int id" "size_t idlen" "int nextid" "size_t *nextidlen"
				.Ft "struct libsysctl_object *"
				.Fn libsysctl_object "int *id" "size_t idlen" "unsigned int flags"
				.Ft "void"
				.Fn libsysctl_freeobject "struct libsysctl_object *object"
				.Ft "struct libsysctl_object_list *"
				.Fn libsysctl_filterlist "libsysctl_filterfunc_t *filterfunc" "unsigned int flags"
				.Ft "struct libsysctl_object_list *"
				.Fn LIBSYSCTL_LIST "unsigned int flags"
				.Ft "struct libsysctl_object_list *"
				.Fn libsysctl_grouplist "int* idstart" "size_t idstartlen" "unsigned int flags" "unsigned int max_depth"
				.Ft "void"
				.Fn libsysctl_freelist "struct libsysctl_object_list* list"
				.Ft "struct libsysctl_object *"
				.Fn libsysctl_tree "int* id" "size_t idlen" "unsigned int flags" "unsigned int max_edge"
				.Ft "void"
				.Fn libsysctl_freetree "struct libsysctl_object *node"
				.Ft "int"
				.Fn LIBSYSCTL_GETVALUE "const int* id" "u_int idlen" "void* valuep" "size_t valuepsize"
				.Ft "int"
				.Fn LIBSYSCTL_SETVALUE "const int* id" "u_int idlen" "const void* valuep" "size_t valuepsize"
				.Ft "int"
				.Fn LIBSYSCTL_OLDNEWVALUE "const int* id" "u_int idlen" "void* oldp" "size_t* oldpsize" "const void* newp" "size_t newpsize"
				.Sh DESCRIPTION
				The
				.Nm libsysctl
				is a interface to the kernel sysctl-mib-tree. It implements wrappers around undocumented
				bcrUnsubmitted Not Done Inline Actions There must be a line break after a sentence stop. bcr: There must be a line break after a sentence stop.
				asicilianoAuthorUnsubmitted Not Done Inline Actions Thank you for your suggestion, I'm updating to fix "mandoc -Tlint" and "igor -Dd" asiciliano: Thank you for your suggestion, I'm updating to fix "mandoc -Tlint" and "igor -Dd"
				.Dq sysctl.*
				kernel states to get mib-entry info and
				provides a convenient API to build a mib-entry,
				entries-list and mib-tree in userspace.
				.Pp
				LIBSYSCTL_IDMAXLEN is useful for
				.Em id
				and
				.Em idlen
				(see
				.Fn libsysctl_next
				below).
				.Pp
				.Fn libsysctl_nametoid
				sets
				.Em id
				and
				.Em idlen
				of the entry with
				.Em name
				and
				.Em namelen.
				.Pp
				.Fn libsysctl_name
				.Fn libsysctl_desc
				.Fn libsysctl_label
				set
				.Em namelen, desclen, labellen
				and
				.Em name, desc, label
				like the entry with
				.Em id
				and
				.Em idlen.
				.Pp
				.Pp
				.Fn LIBSYSCTL_NAMELEN
				.Fn LIBSYSCTL_DESCLEN
				.Fn LIBSYSCTL_LABELLEN
				set
				.Em namelen, desclen, labellen
				of the entry with
				.Em id
				and
				.Em idlen.
				.Pp
				.Fn libsysctl_info
				sets
				.Em info
				and
				.Em infolen
				like the entry with
				.Em id
				and
				.Em idlen, info
				has not a basic format:
				3 bytes for flags, 1 byte for type and a char* for string format; flags and type are defined in
				.In sys/sysctl.h) .
				Macros to deal with
				.Em info:
				.Bd -offset indent -compact
				.Fn LIBSYSCTL_IFLAGS info
				returns flags in an uint32_t;
				.Ed
				.Bd -offset indent -compact
				.Fn LIBSYSCTL_ITYPE info
				returns a unit8_t type;
				.Ed
				.Bd -offset indent -compact
				.Fn LIBSYSCTL_IKIND info
				returns an uint32_t with flags plus type;
				.Ed
				.Bd -offset indent -compact
				.Fn LIBSYSCTL_IFMT info
				returns a char* format_string.
				.Ed
				.Pp
				.Fn libsysctl_nextleaf
				sets
				.Em nextid
				and
				.Em nextidlen
				like the next-leaf-entry of the entry with
				.Em id
				and
				.Em idlen.
				.Fn libsysctl_nextnode
				sets
				.Em nextid
				and
				.Em nextidlen
				like the next-[node\|leaf]-entry of the entry with
				.Em id
				and
				.Em idlen.
				Notes:
				.Em nextid
				should have size LIBSYSCTL_IDMAXLEN and before every call to libsysctl_next*()
				.Em idlen
				should be set to LIBSYSCTL_IDMAXLEN.
				.Pp
				.Fn libsysctl_object
				returns in the heap a
				.Em struct libsysctl_object
				(setting
				.Em flags
				fields) of the entry with
				.Em id
				and
				.Em idlen.
				A mib userspace object/entry is defined:
				.Pp
				.Bd -literal -offset indent -compact
				/* 'struct libsysctl_object': userspace mib entry definition */

				SLIST_HEAD(libsysctl_object_list, libsysctl_object);

				struct libsysctl_object {
				int *id;
				size_t idlen;
				char *name;
				size_t namelen;
				char *desc;
				size_t desclen;
				char *label;
				size_t labellen;
				uint8_t type;
				uint32_t flags;
				char *fmt;
				size_t fmtlen;
				struct libsysctl_object_list *childs;
				SLIST_ENTRY(libsysctl_object) object_link;
				};

				/* OR-flags: object fields to set */
				#define LIBSYSCTL_FNAME 0x01
				#define LIBSYSCTL_FDESC 0x02
				#define LIBSYSCTL_FINFO 0x04
				#define LIBSYSCTL_FLABEL 0x08
				#define LIBSYSCTL_FTYPE 0x10
				#define LIBSYSCTL_FFLAGS 0x20
				#define LIBSYSCTL_FFMT 0x40
				#define LIBSYSCTL_FALL LIBSYSCTL_FNAME \| LIBSYSCTL_FDESC \|
				LIBSYSCTL_FINFO \| LIBSYSCTL_FLABEL \|
				LIBSYSCTL_FTYPE \| LIBSYSCTL_FFLAGS \|
				LIBSYSCTL_FFMT
				.Ed
				.Pp
				.Fn libsysctl_filterlist
				returns a SLIST of libsysctl_object (with
				.Em flags
				), an object o is added when
				.Bd -offset indent -compact
				int libsysctl_filterfunc_t (struct libsysctl_object *o)
				.Ed
				returns 0; note: object.childs is not set.
				.Pp
				.Fn LIBSYSCTL_LIST
				is an alias for
				.Fn libsysctl_filterlist NULL flags
				.Pp
				.Fn libsysctl_grouplist
				returns a SLIST of libsysctl_object (with
				.Em flags
				) that represents a
				.Dq linear
				tree of
				.Em max_depth
				in heap memory, the root is the entry with
				.Em id
				and
				.Em idlen;
				note: object.childs is not set.
				.Pp
				.Fn libsysctl_tree
				returns a tree with
				.Em max_edge
				of libsysctl_object node (with
				.Em flags
				) in heap memory,
				brooksUnsubmitted Not Done Inline Actions I think I'd just talk about allocated memory rather than heap. brooks: I think I'd just talk about allocated memory rather than heap.
				asicilianoAuthorUnsubmitted Done Inline Actions fixed, change: "heap" -> "allocated memory" asiciliano: fixed, change: "heap" -> "allocated memory"
				the root is the entry with
				.Em id
				and
				.Em idlen;
				note: object.childs is set and iterable by SLIST macros.
				.Pp
				.Fn libsysctl_freeobject
				.Fn libsysctl_freelist
				.Fn libsysctl_freetree
				to free heap memory
				.Pp
				.Nm libsysctl
				is not designed to get and set kernel states (use
				.Xr sysctl 3
				),
				anyway useful macros are defined:
				.Fn LIBSYSCTL_GETVALUE
				.Fn LIBSYSCTL_SETVALUE
				.Fn LIBSYSCTL_OLDNEWVALUE
				.Sh IMPLEMENTATION NOTES
				.Nm libsysctl
				calls
				.Fn sysctl
				syscall for wrapping 0.[1-6] entries defined in kern_sysctl.c.
				Kernel returns only next leaf,
				.Fn libsysctl_nextnode
				requires extra computation.
				.Sh RETURN VALUES
				.Rv -std libsysctl_nametoid libsysctl_name libsysctl_nametoid libsysctl_name libsysctl_desc libsysctl_label libsysctl_info libsysctl_nextnode libsysctl_nextleaf LIBSYSCTL_GETVALUE LIBSYSCTL_SETVALUE LIBSYSCTL_OLDNEWVALUE
				.Pp
				The
				.Fn libsysctl_object ,
				.Fn libsysctl_filterlist ,
				.Fn LIBSYSCTL_LIST ,
				.Fn libsysctl_grouplist ,
				.Fn libsysctl_tree
				return
				.Dv NULL
				upon error and a pointer to heap for success.
				.Sh EXAMPLES
				Complete set of examples:
				.Dl https://gitlab.com/alfix/libsysctl/tree/master/examples
				.\" .Sh ERRORS
				.\" For sections 2, 3, 4, and 9 errno settings only.
				.Sh SEE ALSO
				.Xr sysctl 3
				.Xr queue 3
				.Xr nsysctl 8
				.Xr sysctlview 1
				.Sh HISTORY
				The
				.Nm libsysctl
				library first appeared in
				.Fx 13.0 .
				.Sh AUTHORS
				.Nm libsysctl
				was written by
				dabUnsubmitted Not Done Inline Actions Again, here it both says the library isn't designed to get/set kernel state, yet the macros are defined anyway. See comments above about this. If these are kept, I would rephrase the text here: [...] .Xr sysctl 3 . However, some macros are defined for this purpose: [...] dab: Again, here it both says the library isn't designed to get/set kernel state, yet the macros are…
				asicilianoAuthorUnsubmitted Done Inline Actions answer up asiciliano: answer up
				.An Alfonso S. Siciliano Aq Mt alf.siciliano@gmail.com
				.\" .Sh CAVEATS
				.Sh BUGS
				Inherited problems from kern_sysctl.c:
				.Bd -offset indent -compact
				libsysctl_name(): false positive.
				.Ed
				.Bd -offset indent -compact
				libsysctl_desc(): entries without desc could return
				.Dq
				or NULL.
				.Ed