Changeset View
Changeset View
Standalone 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-2019 Alfonso Sabato 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 January 10, 2019 | |||||
.Dt LIBSYSCTL 3 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm LIBSYSCTL_IDMAXLEVEL , | |||||
.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_INFOKIND , | |||||
.Nm LIBSYSCTL_INFOTYPE , | |||||
.Nm LIBSYSCTL_INFOFLAGS , | |||||
.Nm LIBSYSCTL_INFOFMT , | |||||
.Nm libsysctl_nextnode , | |||||
.Nm libsysctl_nextleaf , | |||||
.Nm libsysctl_object , | |||||
.Nm libsysctl_freeobject , | |||||
.Nm libsysctl_filterlist , | |||||
.Nm LIBSYSCTL_LIST , | |||||
.Nm LIBSYSCTL_MAXDEPTH , | |||||
.Nm libsysctl_grouplist , | |||||
.Nm libsysctl_freelist , | |||||
.Nm libsysctl_tree , | |||||
.Nm libsysctl_freetree , | |||||
.Nm LIBSYSCTL_GETVALUE , | |||||
.Nm LIBSYSCTL_SETVALUE | |||||
.Nd manage sysctl mib tree in userpace | |||||
.Sh LIBRARY | |||||
.Lb libsysctl | |||||
.Sh SYNOPSIS | |||||
.In sys/types.h | |||||
.In sys/queue.h | |||||
.In libsysctl.h | |||||
.Vt LIBSYSCTL_IDMAXLEVEL; | |||||
.Ft "int" | |||||
.Fn libsysctl_nametoid "const char *name" "size_t namelen" "int *id" "size_t *idlevel" | |||||
.Ft "int" | |||||
.Fn libsysctl_name "int *id" "size_t idlevel" "char *name" "size_t *namelen" | |||||
.Ft "int" | |||||
.Fn LIBSYSCTL_NAMELEN "int *id" "size_t idlevel" "size_t *namelen" | |||||
.Ft "int" | |||||
.Fn libsysctl_desc "int *id" "size_t idlevel" "char *desc" "size_t *desclen" | |||||
.Ft "int" | |||||
.Fn LIBSYSCTL_DESCLEN "int *id" "size_t idlevel" "size_t *desclen" | |||||
.Ft "int" | |||||
.Fn libsysctl_label "int *id" "size_t idlevel" "char *label" "size_t *labellen" | |||||
.Ft "int" | |||||
.Fn LIBSYSCTL_LABELLEN "int *id" "size_t idlevel" "size_t *labellen" | |||||
.Ft "int" | |||||
.Fn libsysctl_info "int *id" "size_t idlevel" "void *info" "size_t *infolen" | |||||
.Ft "uint32_t" | |||||
.Fn LIBSYSCTL_INFOKIND "info" | |||||
.Ft "uint8_t" | |||||
.Fn LIBSYSCTL_INFOTYPE "info" | |||||
.Ft "uint32_t" | |||||
.Fn LIBSYSCTL_INFOFLAGS "info" | |||||
.Ft "char *" | |||||
.Fn LIBSYSCTL_INFOFMT "info" | |||||
.Ft "int" | |||||
.Fn libsysctl_nextleaf "int *id" "size_t idlevel" "int *nextid" "size_t *nextidlevel" | |||||
.Ft "int" | |||||
.Fn libsysctl_nextnode "int *id" "size_t idlevel" "int *nextid" "size_t *nextidlevel" | |||||
.Ft "struct libsysctl_object *" | |||||
.Fn libsysctl_object "int *id" "size_t idlevel" "unsigned int flags" | |||||
.Ft "void" | |||||
.Fn libsysctl_freeobject "struct libsysctl_object *object" | |||||
.Vt LIBSYSCTL_MAXDEPTH | |||||
.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 idlevel" "unsigned int flags" "unsigned int max_depth" | |||||
.Ft "void" | |||||
.Fn libsysctl_freetree "struct libsysctl_object *node" | |||||
.Ft "int" | |||||
.Fn LIBSYSCTL_GETVALUE "const int *id" "size_t idlevel" "void *valueptr" "size_t *valuesize" | |||||
.Ft "int" | |||||
.Fn LIBSYSCTL_SETVALUE "const int *id" "size_t idlevel" "const void *valueptr" "size_t valuesize" | |||||
.Sh DESCRIPTION | |||||
The | |||||
.Nm libsysctl | |||||
bcr: There must be a line break after a sentence stop. | |||||
Not Done Inline ActionsThank 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" | |||||
is an interface to the kernel sysctl-mib-tree. | |||||
It implements wrappers around undocumented | |||||
.Dq sysctl.* | |||||
kernel states to get mib info and | |||||
provides a convenient API to build a mib-entry, | |||||
entries-list and mib-tree in userspace. | |||||
.Pp | |||||
A mib-entry is identified by a pair | |||||
.Fa "int *id" | |||||
and | |||||
.Fa "size_t idlevel" , | |||||
the level should be between 1 and | |||||
.Vt LIBSYSCTL_IDMAXLEVEL , | |||||
see | |||||
.Fn libsysctl_next | |||||
too. | |||||
.Pp | |||||
.Fn libsysctl_nametoid | |||||
sets | |||||
.Em id | |||||
and | |||||
.Em idlevel | |||||
like the entry with | |||||
.Em name | |||||
and | |||||
.Em namelen . | |||||
.Pp | |||||
.Fn libsysctl_name , | |||||
.Fn libsysctl_desc | |||||
and | |||||
.Fn libsysctl_label | |||||
set | |||||
.Em name | |||||
and | |||||
.Em namelen , | |||||
.Em desc | |||||
and | |||||
.Em desclen , | |||||
.Em label | |||||
and | |||||
.Em labellen | |||||
like the entry with | |||||
.Em id | |||||
and | |||||
.Em idlevel . | |||||
.Pp | |||||
.Fn LIBSYSCTL_NAMELEN , | |||||
.Fn LIBSYSCTL_DESCLEN | |||||
and | |||||
.Fn LIBSYSCTL_LABELLEN | |||||
set | |||||
.Em namelen , | |||||
.Em desclen , | |||||
and | |||||
.Em labellen | |||||
like the entry with | |||||
.Em id | |||||
and | |||||
.Em idlevel . | |||||
.Pp | |||||
.Fn libsysctl_info | |||||
sets | |||||
.Em info | |||||
and | |||||
.Em infolen | |||||
like the entry with | |||||
.Em id | |||||
and | |||||
.Em idlevel , | |||||
.Em 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 -ragged -offset indent -compact | |||||
.Fn LIBSYSCTL_INFOFLAGS info | |||||
returns flags; | |||||
.Ed | |||||
.Bd -ragged -offset indent -compact | |||||
.Fn LIBSYSCTL_INFOTYPE info | |||||
returns entry type; | |||||
.Ed | |||||
.Bd -ragged -offset indent -compact | |||||
.Fn LIBSYSCTL_INFOKIND info | |||||
returns flags following by type; | |||||
.Ed | |||||
.Bd -ragged -offset indent -compact | |||||
.Fn LIBSYSCTL_INFOFMT info | |||||
returns a pointer to | |||||
.Dq format_string . | |||||
.Ed | |||||
.Pp | |||||
.Fn libsysctl_nextleaf | |||||
sets | |||||
.Em nextid | |||||
and | |||||
.Em nextidlevel | |||||
like the next-leaf-entry of the entry with | |||||
.Em id | |||||
and | |||||
.Em idlevel . | |||||
.Fn libsysctl_nextnode | |||||
sets | |||||
.Em nextid | |||||
and | |||||
.Em nextidlevel | |||||
like the next-[node|leaf]-entry of the entry with | |||||
.Em id | |||||
and | |||||
.Em idlevel . | |||||
Notes: | |||||
.Em nextid | |||||
should have size LIBSYSCTL_IDMAXLEVEL and | |||||
.Em nextidlevel | |||||
should be set to LIBSYSCTL_IDMAXLEVEL before to call | |||||
.Fn libsysctl_nextleaf | |||||
or | |||||
.Fn libsysctl_nextnode . | |||||
.Pp | |||||
.Fn libsysctl_object | |||||
returns a pointer to allocated memory for a | |||||
.Em struct libsysctl_object | |||||
(setting | |||||
.Em flags | |||||
members) of the entry with | |||||
.Em id | |||||
and | |||||
.Em idlevel . | |||||
A mib userspace 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 { | |||||
SLIST_ENTRY(libsysctl_object) object_link; | |||||
int *id; | |||||
size_t idlevel; /* between 1 and LIBSYSCTL_IDMAXLEVEL */ | |||||
char *name; | |||||
char *desc; | |||||
char *label; /* aggregation label */ | |||||
uint8_t type; /* defined in <sys/sysctl.h> */ | |||||
uint32_t flags; /* defined in <sys/sysctl.h> */ | |||||
char *fmt; /* format string */ | |||||
/* children is set by libsysctl_tree() */ | |||||
struct libsysctl_object_list *children; | |||||
}; | |||||
/* | |||||
* OR_FLAGS: object fields to set, | |||||
* .id and .idlevel are always set | |||||
* .children is default for libsysctl_tree() | |||||
*/ | |||||
#define LIBSYSCTL_FNAME 0x01 /* .name */ | |||||
#define LIBSYSCTL_FDESC 0x02 /* .desc */ | |||||
#define LIBSYSCTL_FLABEL 0x04 /* .label */ | |||||
#define LIBSYSCTL_FTYPE 0x08 /* .type */ | |||||
#define LIBSYSCTL_FFLAGS 0x10 /* .flags */ | |||||
#define LIBSYSCTL_FFMT 0x20 /* .fmt */ | |||||
#define LIBSYSCTL_FALL /* all */ | |||||
.Ed | |||||
.Pp | |||||
.Fn LIBSYSCTL_LIST | |||||
allocates memory and returns a SLIST of libsysctl_object (setting | |||||
.Em flags | |||||
members), it is an alias for | |||||
.Fn libsysctl_filterlist NULL flags . | |||||
.Pp | |||||
.Fn libsysctl_filterlist | |||||
allocates memory for a SLIST of libsysctl_object (setting | |||||
.Em flags | |||||
members), an object | |||||
.Dq o | |||||
is added if | |||||
.Bd -ragged -offset indent -compact | |||||
int libsysctl_filterfunc_t (struct libsysctl_object *o) | |||||
.Ed | |||||
returns 0 or | |||||
Not Done Inline ActionsI think I'd just talk about allocated memory rather than heap. brooks: I think I'd just talk about allocated memory rather than heap. | |||||
Done Inline Actionsfixed, change: "heap" -> "allocated memory" asiciliano: fixed, change: "heap" -> "allocated memory" | |||||
.Em filterfunc | |||||
is NULL; notes: | |||||
.Fn libsysctl_filterlist | |||||
uses | |||||
.Fn libsysctl_nextnode | |||||
and object.children is not set. | |||||
.Pp | |||||
.Fn libsysctl_grouplist | |||||
allocates memory and returns a SLIST of libsysctl_object (setting | |||||
.Em flags | |||||
members) visited in a | |||||
.Dq Depth First Traversal | |||||
until | |||||
.Em max_depth , | |||||
.Em id | |||||
and | |||||
.Em idlevel | |||||
denote the root. | |||||
Notes: | |||||
.Fn libsysctl_grouplist | |||||
uses | |||||
.Fn libsysctl_nextnode , | |||||
object.children is not set and | |||||
.Em max_depth | |||||
can be set to | |||||
.Vt LIBSYSCTL_MAXDEPTH . | |||||
.Pp | |||||
.Fn libsysctl_tree | |||||
allocates memory for a tree of libsysctl_object nodes (setting | |||||
.Em flags | |||||
members) until | |||||
.Em max_depth | |||||
and returns a pointer to the root: the entry with | |||||
.Em id | |||||
and | |||||
.Em idlevel . | |||||
Notes: | |||||
.Em max_depth | |||||
can be set to | |||||
.Vt LIBSYSCTL_MAXDEPTH , | |||||
object.children is set and iterable by SLIST macros. | |||||
.Pp | |||||
.Fn libsysctl_freeobject , | |||||
.Fn libsysctl_freelist | |||||
and | |||||
.Fn libsysctl_freetree | |||||
free allocated 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 | |||||
and | |||||
.Fn LIBSYSCTL_SETVALUE . | |||||
dabUnsubmitted Not Done Inline ActionsAgain, 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: [...] dab: Again, here it both says the library isn't designed to get/set kernel state, yet the macros are… | |||||
asicilianoAuthorUnsubmitted Done Inline Actionsanswer up asiciliano: answer up | |||||
.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_NAMELEN libsysctl_name LIBSYSCTL_DESCLEN libsysctl_desc LIBSYSCTL_LABELLEN libsysctl_label libsysctl_info libsysctl_nextnode libsysctl_nextleaf LIBSYSCTL_GETVALUE LIBSYSCTL_SETVALUE | |||||
.Pp | |||||
The | |||||
.Fn libsysctl_object , | |||||
.Fn libsysctl_filterlist , | |||||
.Fn LIBSYSCTL_LIST , | |||||
.Fn libsysctl_grouplist , | |||||
.Fn libsysctl_tree | |||||
return | |||||
.Dv NULL | |||||
upon error or a pointer to allocated memory 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 queue 3 , | |||||
.Xr sysctl 3 | |||||
.Sh HISTORY | |||||
The | |||||
.Nm libsysctl | |||||
library first appeared in | |||||
.Fx 13.0 . | |||||
.Sh AUTHORS | |||||
.Nm libsysctl | |||||
and this manual page were written by | |||||
.An Alfonso S. Siciliano Aq Mt alf.siciliano@gmail.com | |||||
.\" .Sh CAVEATS | |||||
.Sh BUGS | |||||
Problems from kern_sysctl.c: | |||||
.Bd -ragged -offset indent -compact | |||||
libsysctl_name() false positive. | |||||
.Ed | |||||
.Bd -ragged -offset indent -compact | |||||
libsysctl_desc() entries without desc could return | |||||
.Dq | |||||
or NULL. | |||||
.Ed |
There must be a line break after a sentence stop.