Page MenuHomeFreeBSD
Differential D18696 Diff 53353 lib/libutil/sysctlmibinfo.3

Changeset View

Standalone View

View Options

lib/libutil/sysctlmibinfo.3

PropertyOld ValueNew Value
svn:eol-stylenullnative
\ No newline at end of property
svn:keywordsnullFreeBSD=%H
\ No newline at end of property
svn:mime-typenulltext/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.
.\"
.\" $FreeBSD$
.\"
.Dd January 29, 2019
.Dt SYSCTLMIBINFO 3
.Os
.Sh NAME
.Nm SYSCTLMIF_MAXIDLEVEL ,
.Nm sysctlmif_nametoid ,
.Nm sysctlmif_name ,
.Nm SYSCTLMIF_NAMELEN ,
.Nm sysctlmif_desc ,
.Nm SYSCTLMIF_DESCLEN ,
.Nm sysctlmif_label ,
.Nm SYSCTLMIF_LABELLEN ,
.Nm sysctlmif_info ,
.Nm SYSCTLMIF_INFOKIND ,
.Nm SYSCTLMIF_INFOTYPE ,
.Nm SYSCTLMIF_INFOFLAGS ,
.Nm SYSCTLMIF_INFOFMT ,
.Nm sysctlmif_nextnode ,
.Nm sysctlmif_nextleaf ,
.Nm sysctlmif_object ,
.Nm sysctlmif_freeobject ,
.Nm sysctlmif_filterlist ,
.Nm SYSCTLMIF_LIST ,
.Nm SYSCTLMIF_MAXDEPTH ,
.Nm sysctlmif_grouplist ,
.Nm sysctlmif_freelist ,
.Nm sysctlmif_tree ,
.Nm sysctlmif_freetree
.Nd get sysctl mib information
.Sh LIBRARY
.Lb libutil
.Sh SYNOPSIS
.In sys/types.h
.In sys/queue.h
.In sysctlmibinfo.h
.Fd #define SYSCTLMIF_MAXIDLEVEL;
.Ft "int"
.Fo sysctlmif_nametoid
.Fa "const char *name"
.Fa "size_t namelen"
.Fa "int *id"
.Fa "size_t *idlevel"
.Fc
.Ft "int"
.Fn sysctlmif_name "int *id" "size_t idlevel" "char *name" "size_t *namelen"
.Ft "int"
.Fn SYSCTLMIF_NAMELEN "int *id" "size_t idlevel" "size_t *namelen"
.Ft "int"
.Fn sysctlmif_desc "int *id" "size_t idlevel" "char *desc" "size_t *desclen"
.Ft "int"
.Fn SYSCTLMIF_DESCLEN "int *id" "size_t idlevel" "size_t *desclen"
.Ft "int"
.Fn sysctlmif_label "int *id" "size_t idlevel" "char *label" "size_t *labellen"
.Ft "int"
.Fn SYSCTLMIF_LABELLEN "int *id" "size_t idlevel" "size_t *labellen"
.Ft "int"
.Fn sysctlmif_info "int *id" "size_t idlevel" "void *info" "size_t *infolen"
.Ft "uint32_t"
.Fn SYSCTLMIF_INFOKIND "info"
.Ft "uint8_t"
.Fn SYSCTLMIF_INFOTYPE "info"
.Ft "uint32_t"
.Fn SYSCTLMIF_INFOFLAGS "info"
.Ft "char *"
.Fn SYSCTLMIF_INFOFMT "info"
.Ft "int"
.Fo sysctlmif_nextleaf
.Fa "int *id"
.Fa "size_t idlevel"
.Fa "int *nextid"
.Fa "size_t *nextidlevel"
.Fc
.Ft "int"
.Fo sysctlmif_nextnode
.Fa "int *id"
.Fa "size_t idlevel"
.Fa "int *nextid"
.Fa "size_t *nextidlevel"
.Fc
.Ft "struct sysctlmif_object *"
.Fn sysctlmif_object "int *id" "size_t idlevel" "unsigned int flags"
.Ft "void"
.Fn sysctlmif_freeobject "struct sysctlmif_object *object"
.Fd #define SYSCTLMIF_MAXDEPTH
.Ft "struct sysctlmif_object_list *"
.Fo sysctlmif_filterlist
.Fa "sysctlmif_filterfunc_t *filterfunc"
.Fa "unsigned int flags"
.Fc
.Ft "struct sysctlmif_object_list *"
.Fn SYSCTLMIF_LIST "unsigned int flags"
.Ft "struct sysctlmif_object_list *"
.Fo sysctlmif_grouplist
.Fa "int *idstart"
.Fa "size_t idstartlen"
.Fa "unsigned int flags"
.Fa "unsigned int max_depth"
.Fc
.Ft "void"
.Fn sysctlmif_freelist "struct sysctlmif_object_list *list"
.Ft "struct sysctlmif_object *"
.Fo sysctlmif_tree
.Fa "int *id"
.Fa "size_t idlevel"
.Fa "unsigned int flags"
.Fa "unsigned int max_depth"
.Fc
.Ft "void"
.Fn sysctlmif_freetree "struct sysctlmif_object *node"
.Sh DESCRIPTION
The
.Nm sysctlmibinfo
library is an interface to the kernel sysctl-mib-tree.
It implements wrappers around undocumented
.Dq sysctl.*
kernel states to get mib information and
provides a convenient API to build a mib-entry,
entries-list and mib-tree in userspace;
as it is not designed to get and set entry values,
anyone wishing to do this should see
debdrupUnsubmitted
Not Done
Inline Actions

Maybe you should rephrase this as "as it is not designed to get and set entry values, anyone wishing to do this should see sysctl(3)"?

debdrup: Maybe you should rephrase this as "as it is not designed to get and set entry values, anyone…
asicilianoAuthorUnsubmitted
Done
Inline Actions

Ok, I'll update

asiciliano: Ok, I'll update
.Xr sysctl 3 .
.Pp
A mib-entry is identified by a pair
.Fa "int *id"
and
.Fa "size_t idlevel" ,
the level should be between 1 and
.Dv SYSCTLMIF_MAXIDLEVEL ,
see
.Fn sysctlmif_next .
.Pp
.Fn sysctlmif_nametoid
sets
.Em id
and
.Em idlevel
like the entry with
.Em name
and
.Em namelen .
.Pp
.Fn SYSCTLMIF_NAMELEN ,
.Fn SYSCTLMIF_DESCLEN
and
.Fn SYSCTLMIF_LABELLEN
set
.Em namelen ,
.Em desclen ,
and
.Em labellen
like the entry with
.Em id
and
.Em idlevel .
.Pp
.Fn sysctlmif_name ,
.Fn sysctlmif_desc
and
.Fn sysctlmif_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 sysctlmif_info
sets
.Em info
and
.Em infolen
like the entry with
.Em id
and
.Em idlevel ,
.Em info
has the format:
debdrupUnsubmitted
Not Done
Inline Actions

Doesn't this sentence become a double negative?

debdrup: Doesn't this sentence become a double negative?
dabUnsubmitted
Not Done
Inline Actions

s/has not a/has the/

dab: s/has not a/has the/
asicilianoAuthorUnsubmitted
Done
Inline Actions

Thank you, I' ll change to fix

asiciliano: Thank you, I' ll change to fix
3 bytes for flags, 1 byte for type and a string for the
.Dq format string ;
flags and type are defined in
.In sys/sysctl.h .
Macros to deal with
.Em info :
.Bd -ragged -offset indent -compact
.Fn SYSCTLMIF_INFOFLAGS info
returns flags;
.Ed
.Bd -ragged -offset indent -compact
.Fn SYSCTLMIF_INFOTYPE info
returns entry type;
.Ed
.Bd -ragged -offset indent -compact
.Fn SYSCTLMIF_INFOKIND info
returns flags following by type;
.Ed
.Bd -ragged -offset indent -compact
.Fn SYSCTLMIF_INFOFMT info
returns a pointer to the
.Dq format string .
.Ed
.Pp
.Fn sysctlmif_nextleaf
sets
.Em nextid
and
.Em nextidlevel
like the next-leaf-entry of the entry with
.Em id
and
.Em idlevel .
.Fn sysctlmif_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
.Dv SYSCTLMIF_MAXIDLEVEL
and
.Em nextidlevel
should be set to
.Dv SYSCTLMIF_MAXIDLEVEL
before to call
.Fn sysctlmif_nextleaf
or
.Fn sysctlmif_nextnode .
.Pp
.Fn sysctlmif_object
returns a pointer to allocated memory for a
.Em struct sysctlmif_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 sysctlmif_object': userspace mib entry definition */
SLIST_HEAD(sysctlmif_object_list, sysctlmif_object);
struct sysctlmif_object {
SLIST_ENTRY(sysctlmif_object) object_link;
int *id;
size_t idlevel; /* between 1 and SYSCTLMIF_MAXIDLEVEL */
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 sysctlmif_tree() */
struct sysctlmif_object_list *children;
};
/*
* OR_FLAGS: object fields to set,
* .id and .idlevel are always set
* .children is default for sysctlmif_tree()
*/
#define SYSCTLMIF_FNAME 0x01 /* .name */
#define SYSCTLMIF_FDESC 0x02 /* .desc */
#define SYSCTLMIF_FLABEL 0x04 /* .label */
#define SYSCTLMIF_FTYPE 0x08 /* .type */
#define SYSCTLMIF_FFLAGS 0x10 /* .flags */
#define SYSCTLMIF_FFMT 0x20 /* .fmt */
#define SYSCTLMIF_FALL /* all */
.Ed
.Pp
.Fn SYSCTLMIF_LIST
allocates memory and returns a SLIST of sysctlmif_object (setting
.Em flags
members), it is an alias for
.Fn sysctlmif_filterlist NULL flags .
.Pp
.Fn sysctlmif_filterlist
allocates memory for a SLIST of sysctlmif_object (setting
.Em flags
members), an object
.Dq o
is added if
.Bd -ragged -offset indent -compact
int sysctlmif_filterfunc_t (struct sysctlmif_object *o)
.Ed
returns 0 or
.Em filterfunc
is NULL; notes:
.Fn sysctlmif_filterlist
uses
.Fn sysctlmif_nextnode
and object.children is not set.
.Pp
.Fn sysctlmif_grouplist
allocates memory and returns a SLIST of sysctlmif_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 sysctlmif_grouplist
uses
.Fn sysctlmif_nextnode ,
object.children is not set and
.Em max_depth
can be set to
.Dv SYSCTLMIF_MAXDEPTH .
.Pp
.Fn sysctlmif_tree
allocates memory for a tree of sysctlmif_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
.Dv SYSCTLMIF_MAXDEPTH ,
object.children is set and iterable by SLIST macros.
.Pp
.Fn sysctlmif_freeobject ,
.Fn sysctlmif_freelist
and
.Fn sysctlmif_freetree
free allocated memory.
.Sh IMPLEMENTATION NOTES
.Nm sysctlmibinfo
uses
.Fn sysctl
syscall for wrapping 0.[1-6] entries defined in kern_sysctl.c.
The kernel returns only next leaf,
.Fn sysctlmif_nextnode
requires extra computation.
.Sh RETURN VALUES
.Rv -std sysctlmif_nametoid SYSCTLMIF_NAMELEN sysctlmif_name SYSCTLMIF_DESCLEN sysctlmif_desc SYSCTLMIF_LABELLEN sysctlmif_label sysctlmif_info sysctlmif_nextnode sysctlmif_nextleaf
.Pp
The
.Fn sysctlmif_object ,
.Fn sysctlmif_filterlist ,
.Fn SYSCTLMIF_LIST ,
.Fn sysctlmif_grouplist ,
.Fn sysctlmif_tree
functions return
.Dv NULL
upon error or a pointer to allocated memory for success.
.Sh EXAMPLES
Complete set of examples:
.Dl https://gitlab.com/alfix/sysctlmibinfo/tree/master/examples
.Sh SEE ALSO
.Xr queue 3 ,
.Xr sysctl 3
.Sh HISTORY
The
.Nm sysctlmibinfo
library first appeared in
.Fx 13.0 .
.Sh AUTHORS
.Nm sysctlmibinfo
and this manual page were written by
.An Alfonso S. Siciliano Aq Mt alf.siciliano@gmail.com
.Sh BUGS
Problems from the kernel space:
.Bd -ragged -offset indent -compact
.Fn sysctlmif_name
false positive.
.Ed
.Bd -ragged -offset indent -compact
.Fn sysctlmif_desc
could set
.Em desc
to:
.Dq
or
.Dv NULL
for entries without description.
.Ed