Alfonso Siciliano

FreeBSD System Calls Table

2021-01-02T18:00:00+00:00

The “FreeBSD syscalls table” is available on the new Blog.

Disable sysctl ANYBODY flag

2020-07-11T18:00:00+00:00

FreeBSD provides the sysctl system call and a wrapper utility to get or set the state of the kernel at run time (the handbook shows some useful example). Every user can get the value of a parameter:

% sysctl kern.maxprocperuid
kern.maxprocperuid: 6656

but, only the root user can usually set a value. Example:

% sysctl kern.maxprocperuid=10000
kern.maxprocperuid: 6656
sysctl: kern.maxprocperuid=10000: Operation not permitted
% su
# sysctl kern.maxprocperuid=10000
kern.maxprocperuid: 6656 -> 10000

Some parameter has the CTLFLAG_ANYBODY flag, so it is settable by every user. We can use the nsysctl utility to find them:

% nsysctl -aNGI | grep ANYBODY
kern.proc.args:  RD WR RW ANYBODY MPSAFE CAPWR
kern.proc.rlimit:  RD WR RW ANYBODY MPSAFE
kern.proc.osrel:  RD WR RW ANYBODY MPSAFE
kern.devname:  RD WR RW ANYBODY MPSAFE
hw.psm.elantech.natural_scroll:  RD WR RW ANYBODY DYN
hw.psm.elantech.three_finger_drag:  RD WR RW ANYBODY DYN
hw.psm.elantech.touchpad_off:  RD WR RW ANYBODY DYN
hw.psm.elantech.vscroll_div_max:  RD WR RW ANYBODY DYN
hw.psm.elantech.vscroll_div_min:  RD WR RW ANYBODY DYN
hw.psm.elantech.vscroll_min_delta:  RD WR RW ANYBODY DYN
hw.psm.elantech.vscroll_ver_area:  RD WR RW ANYBODY DYN
hw.psm.elantech.vscroll_hor_area:  RD WR RW ANYBODY DYN
hw.psm.elantech.taphold_timeout:  RD WR RW ANYBODY DYN
hw.psm.elantech.tap_min_queue:  RD WR RW ANYBODY DYN
hw.psm.elantech.tap_max_delta:  RD WR RW ANYBODY DYN
hw.psm.elantech.div_len:  RD WR RW ANYBODY DYN
hw.psm.elantech.div_max_na:  RD WR RW ANYBODY DYN
hw.psm.elantech.div_max:  RD WR RW ANYBODY DYN
hw.psm.elantech.div_min:  RD WR RW ANYBODY DYN
hw.psm.elantech.weight_len_squared:  RD WR RW ANYBODY DYN
hw.psm.elantech.weight_previous_na:  RD WR RW ANYBODY DYN
hw.psm.elantech.weight_previous:  RD WR RW ANYBODY DYN
hw.psm.elantech.weight_current:  RD WR RW ANYBODY DYN
hw.psm.elantech.multiplicator:  RD WR RW ANYBODY DYN
hw.psm.elantech.window_max:  RD WR RW ANYBODY DYN
hw.psm.elantech.window_min:  RD WR RW ANYBODY DYN
hw.psm.elantech.na_left:  RD WR RW ANYBODY DYN
hw.psm.elantech.na_bottom:  RD WR RW ANYBODY DYN
hw.psm.elantech.na_right:  RD WR RW ANYBODY DYN
hw.psm.elantech.na_top:  RD WR RW ANYBODY DYN
hw.psm.elantech.margin_left:  RD WR RW ANYBODY DYN
hw.psm.elantech.margin_bottom:  RD WR RW ANYBODY DYN
hw.psm.elantech.margin_right:  RD WR RW ANYBODY DYN
hw.psm.elantech.margin_top:  RD WR RW ANYBODY DYN
hw.psm.elantech.max_width:  RD WR RW ANYBODY DYN
hw.psm.elantech.max_pressure:  RD WR RW ANYBODY DYN
hw.psm.elantech.min_pressure:  RD WR RW ANYBODY DYN
hw.psm.elantech.two_finger_scroll:  RD WR RW ANYBODY DYN MPSAFE
hw.psm.elantech.max_y:  RD ANYBODY DYN MPSAFE
hw.psm.elantech.max_x:  RD ANYBODY DYN MPSAFE
hw.psm.elantech.directional_scrolls:  RD WR RW ANYBODY DYN MPSAFE
hw.snd.default_unit:  RD WR RW ANYBODY TUN RDTUN RWTUN NOFETCH

Generally they are the parameters for setting up a Desktop/Laptop, hw.psm.* for the touchpad and hw.snd.default_unit to define the default audio unit, the others parameters are not writable because are CTLTYPE_NODEs

% nsysctl -Nt kern.proc.args kern.proc.rlimit kern.proc.osrel kern.devname
kern.proc.args: node
kern.proc.rlimit: node
kern.proc.osrel: node
kern.devname: opaque

or CTLTYPE_OPAQUE (devname(3)).

The Problem

I think this flag is an useful feature, indeed a not-root user can use mixertui to set hw.snd.default_unit just pressing F8. However, a question in the FreeBSD hacker mailing list was about “an option to disable CTLFLAG_ANYBODY flag: only the root user should set a sysctl value”.

Solution 1

The first solution was to change an if condition in kern_sysctl.c

	/* Is this sysctl writable by only privileged users? */
	if (req->newptr && !(oid->oid_kind & CTLFLAG_ANYBODY)) {
		int priv;

		if (oid->oid_kind & CTLFLAG_PRISON)
			priv = PRIV_SYSCTL_WRITEJAIL;
#ifdef VIMAGE
		else if ((oid->oid_kind & CTLFLAG_VNET) &&
		     prison_owns_vnet(req->td->td_ucred))
			priv = PRIV_SYSCTL_WRITEJAIL;
#endif
		else
			priv = PRIV_SYSCTL_WRITE;
		error = priv_check(req->td, priv);
		if (error)
			goto out;
	}

from

/* Is this sysctl writable by only privileged users? */
if (req->newptr && !(oid->oid_kind & CTLFLAG_ANYBODY)) {

/* Is this sysctl writable? */
if (req->newptr) {

so, the ANYBODY flag is deleted: sysctl() has to call/check priv_check() every time a new value is passed. This solution is correct because only the root user can set a value but it has a problem: a normal user can’t use the utility to get a value:

% sysctl hw.snd.default_unit
sysctl: unknown oid 'hw.snd.default_unit'
% su
# sysctl hw.snd.default_unit
hw.snd.default_unit: 1

Solution 2

What is the unknown oid error with a not-root user?
The utility uses a special sysctl object: sysctl.name2oid to convert the name of a parameter in its corresponding Object ID, indeed the system call uses a numeric ID (OID) to specify a parameter not its name. The utility calls sysctl() with the name in the new buffer (req->newptr) and sysctl.name2oid fills the old buffer with the OID, pseudocode:

sysctl( 0.3 sysctl.name2oid, OID, sizeOID, "name", strlen("name")+1);

sysctl thinks to set a new value to the parameter, but after the first solution only the root can set a new value so the error of the utility:

sysctl: unknown oid 'hw.snd.default_unit'

Another solution solves the problem, changing the previous if condition in kern_sysctl.c:

from

/* Is this sysctl writable by only privileged users? */
if (req->newptr && !(oid->oid_kind & CTLFLAG_ANYBODY)) {

/*
 * Is this sysctl writable?
 * Does it belong to the undocumented interface or sysctlinfo?
 */
if (req->newptr && !(SYSCTL_CHILDREN(&sysctl___sysctl) == oid->oid_parent)) {

Testing: a not-root user can get the value of an object

% sysctl hw.snd.default_unit
hw.snd.default_unit: 1

but cannot set a value

% sysctl hw.snd.default_unit=0
hw.snd.default_unit: 1
sysctl: hw.snd.default_unit=0: Operation not permitted

despite the object has the ANYBODY flag

% nsysctl -NG hw.snd.default_unit
hw.snd.default_unit:  RD WR RW ANYBODY TUN RDTUN RWTUN NOFETCH

Technical study

A not-root user can use the sysctl utility (with the second solution) because it can “set” a new value to sysctl.name2oid, properly sysctl.name2oid belongs to an undocumented kernel interface, you could refer to the README of the sysctlinfo interface for a more thorough description.

Links

FreeBSD hacker mailing list

BSDCan 2020

2020-06-19T18:00:00+00:00

BSDCan is an annual technical conference for people working on and with 4.4BSD based operating systems and related projects.
I had the honor of being a speaker this year, my talk was: “sysctlinfo: a new interface to visit the FreeBSD sysctl MIB and to pass the object info to userland” (video, slides and paper are available online).

MixerTUI 1.1

2020-04-24T18:00:00+00:00

MixerTUI 1.1 is out!

MixerTUI is an audio mixer with a Terminal User Interface for FreeBSD, the new features of this version are: -d -h -m -v options and TAB to switch view mode.

To install the port audio/mixertui:

# cd /usr/ports/audio/mixertui/ && make install clean

To add the package:

# pkg install mixertui

Options and features:

SYNOPSIS
     mixertui [-c | -h | -v] [-d <unit>] [-m <mixer>]

DESCRIPTION
     The mixertui utility is an audio mixer with a Terminal User Interface.

     The following options are available:

     -c      Disable color.

     -d <unit>
             Show the device with the <unit> number, default sysctl
             hw.snd.default_unit.

     -h      Display options, a short description and exit.

     -m <mixer>
             Use <mixer> to get the list of devices, default /dev/mixer.

     -v      Show version and exit.

     The following user interface features are available:

     Esc Q q
             Exit.

     F1 ? H h
             Open Help window.

     F2      Show Sound Driver information.

     F3      Playback View: show playback controls.

     F4      Capture View: show capture controls.

     F5      All View: show all controls.

     TAB     Switch View F3/F4/F5.

     F6      Select audio device.

     F7      Show audio device information.

     F8      Set current device as default.

     R r     Refresh screen.

     KEY_LEFT
             Previous control.

     KEY_RIGHT
             Next control.

     KEY_UP/KEY_DOWN
             Increment/Decrement volume.

     +/-     Increment/Decrement volume.

     PAGE_UP/PAGE_DOWN
             Increment/Decrement volume in a big step.

     End     Set volume to 0%.

     Home    Set volume to 100%.

     0-9     Set volume to 0%-90%.

     a/s/d   Increment left/both/right volume.

     z/x/c   Decrement left/both/right volume.

     B b     Balance left and right volume.

     M m     Toggle mute.

     </>     Toggle left/right mute.

MixerTUI 0.1

2020-04-02T18:00:00+00:00

MixerTUI 0.1 is out!

MixerTUI is an audio mixer with a Terminal User Interface built on the FreeBSD sound system wiki.freebsd.org/Sound. It can show the current Sound Driver configuration and select an audio device: to get its information, change the volume or to set as default, the last feature allows to switch easily audio from/to laptop and hdmi, headphones and speakers, etc.

To install the port audio/mixertui:

# cd /usr/ports/audio/mixertui/ && make install clean

To add the package:

# pkg install mixertui

To build from the repository:

% git clone https://gitlab.com/alfix/mixertui.git
% cd mixertui
% make
% ./mixertui

Options and features:

SYNOPSIS
     mixertui [-c]

DESCRIPTION
     The mixertui utility is an audio mixer with a Terminal User Interface.

     The following option is available:

     -c      Disable color.

     The following user interface features are available:

     Esc Q q
             Exit.

     F1 H h  Open Help window.

     F2      Show Sound Driver information.

     F3      Playback View: show playback controls.

     F4      Capture View: show capture controls.

     F5      All View: show all controls.

     F6      Select audio device.

     F7      Show audio device information.

     F8      Set current device as default.

     R r     Refresh screen.

     KEY_LEFT
             Previous control.

     KEY_RIGHT
             Next control.

     KEY_UP/KEY_DOWN
             Increment/Decrement volume.

     +/-     Increment/Decrement volume.

     PAGE_UP/PAGE_DOWN
             Increment/Decrement volume in a big step.

     End     Set volume to 0%.

     0-9     Set volume to 0%-90%.

     a/s/d   Increment left/both/right volume.

     z/x/c   Decrement left/both/right volume.

     B b     Balance left and right volume.

     M m     Toggle mute.

     </>     Toggle left/right mute.

sysctlview 2.0

2020-03-29T19:00:00+00:00

sysctlview 2.0 is out!

The sysctl() system call can get or set the state of the system, the FreeBSD kernel exposes the parameters for sysctl() as objects of a Management information Base (MIB).

sysctlview is a graphical sysctl MIB explorer, it shows the properties and the value of an object, the new version 2 allows to set its value, too.

To install the port deskutils/sysctlview:

# cd /usr/ports/deskutils/sysctlview/ && make install clean

To add the package:

# pkg install sysctlview

FreeBSD and Nvidia Optimus

2020-01-05T19:00:00+00:00

This post is a “step by step” tutorial to describe how I can use my Nvidia GeForce GT540M graphic card of my FreeBSD laptop, screenshot.

FreeBSD is a registered trademark of the FreeBSD Foundation, NVIDIA and Optimus are registered trademarks of the NVIDIA Corporation.

“Step 0”
I assume you are using FreeBSD and have a Nvidia Optimus graphic card. My laptop is wiki.freebsd.org/Laptops/Acer_Aspire_5742G, at the time of writing my FreeBSD version is:

% uname -a
FreeBSD fbsd.home 13.0-CURRENT FreeBSD 13.0-CURRENT r352742 GENERIC  amd64

I can use the Intel video card by installing graphics/drm-current-kmod (you may need to install drm-fbsd12.0-kmod or drm-fbsd11.2-kmod), following the instructions of the port and editing the Section “Device” of /etc/X11/xorg.conf:

... extra ...

Section "Device"
        ### Available Driver options are:-
        ### Values: <i>: integer, <f>: float, <bool>: "True"/"False",
        ### <string>: "String", <freq>: "<f> Hz/kHz/MHz",
        ### <percent>: "<f>%"
        ### [arg]: arg optional
        #Option     "ShadowFB"           	# [<bool>]
        #Option     "DefaultRefresh"     	# [<bool>]
        #Option     "ModeSetClearScreen" 	# [<bool>]
	Identifier  "Card0"
	Driver      "intel"
	BusID       "PCI:0:2:0"
EndSection

#Section "Device"
        ### Available Driver options are:-
        ### Values: <i>: integer, <f>: float, <bool>: "True"/"False",
        ### <string>: "String", <freq>: "<f> Hz/kHz/MHz",
        ### <percent>: "<f>%"
        ### [arg]: arg optional
        #Option     "ShadowFB"           	# [<bool>]
        #Option     "DefaultRefresh"     	# [<bool>]
        #Option     "ModeSetClearScreen" 	# [<bool>]
	#Identifier  "Card1"
	#Driver      "vesa"
	#BusID       "PCI:1:0:0"
#EndSection

... extra ...

“Step 1”

Install the Nvidia driver and the optirun utility:

% git clone https://github.com/pouya-eghbali/freebsd-nvidia-optimus.git
% cd freebsd-nvidia-optimus
% sudo mkdir /usr/ports/x11/nvidia-optimus-driver
% sudo cp -pr ./nvidia-optimus-driver /usr/ports/x11
% sudo mkdir /usr/ports/x11/nvidia-optimus-driver-390
% sudo cp -pr ./nvidia-optimus-driver-390 /usr/ports/x11
% cd /usr/ports/x11/nvidia-optimus-driver-390 ; sudo make install clean

I installed the legacy version 390, you could install the latest version:

% cd /usr/ports/x11/nvidia-optimus-driver ; sudo make install clean

Finally you may need to run:

% rehash

“Step 2”

Start the Optimus service:

% sudo /usr/local/etc/rc.d/optimus onestart

The output is:

% sudo /usr/local/etc/rc.d/optimus onestart
Starting optimus
% 
X.Org X Server 1.18.4
Release Date: 2016-07-19
X Protocol Version 11, Revision 0
Build Operating System: FreeBSD 13.0-CURRENT amd64 
Current Operating System: FreeBSD fbsd.home 13.0-CURRENT FreeBSD 13.0-CURRENT r352742 GENERIC amd64
Build Date: 26 September 2019  06:56:18AM
 
Current version of pixman: 0.38.4
	Before reporting problems, check http://wiki.x.org
	to make sure that you have the latest version.
Markers: (--) probed, (**) from config file, (==) default setting,
	(++) from command line, (!!) notice, (II) informational,
	(WW) warning, (EE) error, (NI) not implemented, (??) unknown.
(==) Log file: "/var/log/Xorg.8.log", Time: Sun Jan  5 03:32:11 2020
(++) Using config file: "/usr/local/etc/X11/optimus.x.conf"
(==) Using system config directory "/usr/local/share/X11/xorg.conf.d"

The command could lock the shell, no problem, just type the Enter key

<Press ENTER>

% 

The shell is again ready to run your commands.

“Step 3”

Install games/trigger-rally (http://trigger-rally.sourceforge.net/) and run it

% trigger-rally

Don’t play, close the game, the output should show:

...
Graphics: Intel Open Source Technology Center Mesa DRI Intel(R) Ironlake Mobile 
Using OpenGL 2.1 Mesa 18.3.2
...

Now run

% optirun trigger-rally

Close the game, finally you can see:

...
Graphics: NVIDIA Corporation GeForce GT 540M/PCIe/SSE2
Using OpenGL 4.5.0 NVIDIA 390.116
...

Alike you could install games/sauerbraten, the info about the graphic card is at the top-left corner of the starting screen screenshot.

“Step 4”

Enjoy! Some screenshot:

games/trigger-rally screenshot1
games/0ad screenshot2
games/sauerbraten screenshot3

“Step 5”

Github project: pouya-eghbali/freebsd-nvidia-optimus

FreeBSD port x11/nvidia-driver-optimus (Work In Progress): PR 192617

Problems and Troubleshoot: FreeBSD Forum “nvidia optimus driver for freebsd”

Switch off the Nvidia Optimus card: FreeBSD wiki “TuningPowerConsumption”

Manual sysctlmibinfo2

2019-12-09T19:00:00+00:00

The sysctlmibinfo2 library provides an API to explore the FreeBSD sysctl MIB and to get the info of an object, it is useful to build a sysctl-like tool to get or set the kernel state. For example, sysctlview, a graphical sysctl MIB explorer, depends on it.

This post shows the manual page, for the source code and examples: gitlab.com/alfix/sysctlmibinfo2.

SYSCTLMIBINFO2(3)      FreeBSD Library Functions Manual      SYSCTLMIBINFO2(3)

NAME
     sysctlmif_name, sysctlmif_oidbyname, sysctlmif_oidinputbyname,
     sysctlmif_desc, sysctlmif_descbyname, sysctlmif_label,
     sysctlmif_labelbyname, sysctlmif_fmt, sysctlmif_fmtbyname,
     sysctlmif_kind, sysctlmif_kindbyname, SYSCTLMIF_KINDTYPE,
     SYSCTLMIF_KINDFLAGS, sysctlmif_nextnode, sysctlmif_nextleaf,
     sysctlmif_object, sysctlmif_objectbyname, sysctlmif_freeobject,
     sysctlmif_list, sysctlmif_grouplist, sysctlmif_grouplistbyname,
     sysctlmif_freelist, sysctlmif_tree, sysctlmif_treebyname,
     sysctlmif_freetree, sysctlmif_mib, sysctlmif_freemib - sysctl MIB-Tree
     info API

LIBRARY
     To load the required kernel modules at boot time, place the following
     lines in loader.conf(5):

           sysctlinfo_load="YES"
           sysctlbyname_improved_load="YES"

     library "libsysctlmibinfo2"

SYNOPSIS
     #include <sys/types.h>
     #include <sys/queue.h>
     #include <sysctlmibinfo2.h>

     int
     sysctlmif_name(int *id, size_t idlevel, char *name, size_t *namelen);

     int
     sysctlmif_oidbyname(const char *name, int *id, size_t *idlevel);

     int
     sysctlmif_oidinputbyname(const char *name, int *id, size_t *idlevel);

     int
     sysctlmif_desc(int *id, size_t idlevel, char *desc, size_t *desclen);

     int
     sysctlmif_descbyname(const char *name, char *desc, size_t *desclen);

     int
     sysctlmif_label(int *id, size_t idlevel, char *label, size_t *labellen);

     int
     sysctlmif_labelbyname(const char *name, char *label, size_t *labellen);

     int
     sysctlmif_fmt(int *id, size_t idlevel, char *fmt, size_t *fmtlen);

     int
     sysctlmif_fmtbyname(const char *name, char *fmt, size_t *fmtlen);

     int
     sysctlmif_kind(int *id, size_t idlevel, unsigned int *kind);

     int
     sysctlmif_kindbyname(const char *name, unsigned int *kind);

     unsigned int
     SYSCTLMIF_KINDTYPE(unsigned int kind);

     unsigned int
     SYSCTLMIF_KINDFLAGS(unsigned int kind);

     int
     sysctlmif_nextleaf(int *id, size_t idlevel, int *idnext,
         size_t *idnextlevel);

     int
     sysctlmif_nextnode(int *id, size_t idlevel, int *idnext,
         size_t *idnextlevel);

     struct sysctlmif_object *
     sysctlmif_object(int *id, size_t idlevel);

     struct sysctlmif_object *
     sysctlmif_objectbyname(const char *name);

     void
     sysctlmif_freeobject(struct sysctlmif_object *object);

     struct sysctlmif_object_list *
     sysctlmif_list();

     struct sysctlmif_object_list *
     sysctlmif_grouplist(int *idroot, size_t idrootlen);

     struct sysctlmif_object_list *
     sysctlmif_grouplistbyname(const char *name);

     void
     sysctlmif_freelist(struct sysctlmif_object_list *list);

     struct sysctlmif_object *
     sysctlmif_tree(int *idroot, size_t idrootlevel);

     struct sysctlmif_object *
     sysctlmif_treebyname(const char *name);

     void
     sysctlmif_freetree(struct sysctlmif_object *node);

     struct sysctlmif_object_list *
     sysctlmif_mib();

     void
     sysctlmif_freemib(struct sysctlmif_object_list *mib);

DESCRIPTION
     The sysctlmibinfo2 library is an interface to the kernel sysctl MIB-Tree.
     It implements wrappers around the sysctlinfo(4) interface and
     sysctlbyname-improved to explore the sysctl MIB and to get the info of an
     object, moreover it defines a struct sysctlmif_object and provides a
     convenient API to build data structures of sysctlmif_object; as it is not
     designed to get and set object values, anyone wishing to do this should
     see sysctl(3).

     An object is identified by an Object Identifier (OID), it is represented
     by a pair int *id and size_t idlevel, the level should be between 1 and
     CTL_MAXNAME.

     sysctlmif_name(), sysctlmif_desc(), sysctlmif_kind(), sysctlmif_fmt(),
     sysctlmif_label(), sysctlmif_nextnode() and sysctlmif_nextleaf() set name
     and namelen, desc and desclen, kind, label and labellen, idnext and
     idnextlevel like the object with id / idlevel.  sysctlmif_descbyname(),
     sysctlmif_kindbyname(), sysctlmif_fmtbyname() and sysctlmif_labelbyname()
     are equivalet but the object is identified by its name.

     sysctlmif_oidbyname() and sysctlmif_oidinputbyname() set id and idlevel
     like the object with name, sysctlmif_oidinputbyname() can handle the
     nodes with an input with the OID, e.g., "kern.proc.pid.<input>".

     The previous functions seek the object with id / idlevel or name, then
     the property is copied into the buffer (e.g., desc, label, idnext, etc.).
     Before the call buflen (e.g., desclen, lebellen, idnextlevel, etc.)
     gives the size of buffer, after a successful call buflen gives the amount
     of data copied; the size of the property can be determined with the NULL
     argument for the buffer, the size will be returned in the location
     pointed to by buflen.

     The sysctlmibinfo2 library defines a struct for the info of an object:

           struct sysctlmif_object {
                   SLIST_ENTRY(sysctlmif_object) object_link;
                   int *id;                     /* array of idlevel items    */
                   size_t idlevel;              /* between 1 and CTL_MAXNAME */
                   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             */
                   struct sysctlmif_object_list *children; /* children list  */
           };

     and a list of objects, struct sysctlmif_object_list, iterable by the
     SLIST macros, see queue(3).

     sysctlmif_object() and sysctlmif_objectbyname() return a pointer to the
     allocated memory for a struct sysctlmif_object of the object with id /
     idlevel or name, the pointer can be passed to sysctlmif_freeobject() to
     free the memory.

     sysctlmif_list() allocates memory and returns a list with all the objects
     of the MIB, sysctlmif_freelist() frees the allocated memory.

     sysctlmif_grouplist() and sysctlmif_grouplistbyname() allocate memory and
     returns a list of the objects visited in a "Depth First Traversal", id /
     idlevel or name denote the root, sysctlmif_freelist() frees the allocated
     memory.

     sysctlmif_tree() and sysctlmif_treebyname() allocate memory for a tree of
     sysctlmif_object and returns a pointer to the root, id / idlevel or name
     denote the root, object.children is set and iterable by SLIST macros,
     sysctlmif_freetree() frees the allocated memory.

     sysctlmif_mib() allocates memory for a collection of trees and returns a
     list where the entries are the roots representing the top-level objects,
     sysctlmif_freemib() frees the allocated memory.

RETURN VALUES
     The sysctlmif_name(), sysctlmif_oidbyname(), sysctlmif_oidinputbyname(),
     sysctlmif_desc(), sysctlmif_descbyname(), sysctlmif_label(),
     sysctlmif_labelbyname(), sysctlmif_fmt(), sysctlmif_fmtbyname(),
     sysctlmif_kind(), sysctlmif_kindbyname(), sysctlmif_nextnode(), and
     sysctlmif_nextleaf() functions return the value 0 if successful;
     otherwise the value -1 is returned and the global variable errno is set
     to indicate the error.

     The sysctlmif_object(), sysctlmif_objectbyname(), sysctlmif_list(),
     sysctlmif_grouplist(), sysctlmif_grouplistbyname(), sysctlmif_tree(),
     sysctlmif_treebyname(), sysctlmif_mib() functions return NULL upon error
     or a pointer to allocated memory for success.

EXAMPLES
     Complete set of examples:
           https://gitlab.com/alfix/sysctlmibinfo2/tree/master/examples

     Example to print the Sound Driver objects:

           struct sysctlmif_object_list *list;
           struct sysctlmif_object *obj;

           if ((list = sysctlmif_grouplistbyname("hw.snd")) == NULL)
                   return (1);

           SLIST_FOREACH(obj, list, object_link) {
                   printf("name:   %s\n", obj->name);
                   printf("descr.: %s\n", obj->desc);
                   printf("label:  %s\n", obj->label);
                   printf("flags:  %u\n", obj->flags);
                   printf("type:   %u\n", obj->type);
                   printf("fmt:    %s\n", obj->fmt);
                   printf("----------------------\n");
           }

           sysctlmif_freelist(list);

ERRORS
     The following errors may be reported:

     [ECAPMODE]         The node has not the CTLFLAG_CAPRD or CTLFLAG_CAPWR
                        flag in capability mode.

     [EINVAL]           name has more than CTL_MAXNAME levels.

     [EINVAL]           idlevel is either greater CTL_MAXNAME, equal to zero
                        or is not an integer.

     [ENAMETOOLONG]     name is >= MAXPATHLEN.

     [ENOATTR]          The node exists but its info is NULL.

     [ENOENT]           The node does not exist.

SEE ALSO
     cap_enter(2), queue(3), sysctl(3), sysctlinfo(3), sysctlinfo(4)

HISTORY
     The sysctlmibinfo2 library first appeared in FreeBSD 13.0.

AUTHORS
     sysctlmibinfo2 was written by Alfonso Sabato Siciliano
     <alf.siciliano@gmail.com>

FreeBSD 13.0-CURRENT             April 7, 2020            FreeBSD 13.0-CURRENT

Manuals sysctlinfo

2019-10-02T19:00:00+00:00

sysctlinfo is an interface to explore the sysctl tree and to pass the properties of the nodes to the userland, this post displays the manuals (sysctlinfo.4 and sysctlinfo.3), for an introduction, examples and FAQ: http://gitlab.com/alfix/sysctlinfo.

Legal notice: FreeBSD is a registered trademark of the FreeBSD Foundation.

man 4 sysctlinfo

SYSCTLINFO(4)          FreeBSD Kernel Interfaces Manual          SYSCTLINFO(4)

NAME
     sysctlinfo - a sysctl(3) MIB for getting info about the sysctl tree

SYNOPSIS
     sysctl sysctl.entryfakename
     sysctl sysctl.entryname
     sysctl sysctl.entrydesc
     sysctl sysctl.entrylabel
     sysctl sysctl.entrykind
     sysctl sysctl.entryfmt
     sysctl sysctl.entrynextnode
     sysctl sysctl.entrynextleaf
     sysctl sysctl.entryallinfo
     sysctl sysctl.entryallinfo_withnextnode
     sysctl sysctl.entryallinfo_withnextleaf
     sysctl sysctl.entryfakeidbyname
     sysctl sysctl.entryidbyname
     sysctl sysctl.entrydescbyname
     sysctl sysctl.entrylabelbyname
     sysctl sysctl.entrykindbyname
     sysctl sysctl.entryfmtbyname
     sysctl sysctl.entryallinfobyname
     sysctl sysctl.entryallinfobyname_withnextnode
     sysctl sysctl.entryallinfobyname_withnextleaf

DESCRIPTION
     The sysctlinfo interface explores the sysctl tree to pass the info of the
     nodes to userland, it should be used via sysctlinfo(3).

SEE ALSO
     sysctl(3), sysctlinfo(3)

HISTORY
     The sysctlinfo interface first appeared in FreeBSD 13.0.

AUTHORS
     The sysctlinfo interface was written by Alfonso S. Siciliano
     <alf.siciliano@gmail.com>

FreeBSD 13.0-CURRENT            August 2, 2019            FreeBSD 13.0-CURRENT

man 3 sysctlinfo

SYSCTLINFO(3)          FreeBSD Library Functions Manual          SYSCTLINFO(3)

NAME
     SYSCTLINFO SYSCTLINFO_BYNAME SYSCTLINFO_HELPER_ALL
     SYSCTLINFO_HELPER_ALLIWITHNEXT SYSCTLINFO_HELPER_ALLWITHNEXTNAME -
     Interface for getting info about the sysctl tree

SYNOPSIS
     #include <sys/types.h>
     #include <sys/sysctl.h>
     #include <sysctlinfo.h>

     #define ENTRYFAKENAME
     #define ENTRYNAME
     #define ENTRYDESC
     #define ENTRYLABEL
     #define ENTRYKIND
     #define ENTRYFMT
     #define ENTRYNEXTNODE
     #define ENTRYNEXTLEAF
     #define ENTRYALLINFO
     #define ENTRYALLINFO_WITHNEXTNODE
     #define ENTRYALLINFO_WITHNEXTLEAF
     #define ENTRYIDBYNAME
     #define ENTRYFAKEIDBYNAME
     #define ENTRYDESCBYNAME
     #define ENTRYLABELBYNAME
     #define ENTRYKINDBYNAME
     #define ENTRYFMTBYNAME
     #define ENTRYALLINFOBYNAME
     #define ENTRYALLINFOBYNAME_WITHNEXTNODE
     #define ENTRYALLINFOBYNAME_WITHNEXTLEAF

     int
     SYSCTLINFO(int *id, size_t idlevel, int prop[2], void *buf,
         size_t *buflen);

     int
     SYSCTLINFO_BYNAME(char *name, int prop[2], void *buf, size_t *buflen);

     void
     SYSCTLINFO_HELPER_ALL(void *buf, size_t idlevel, int *id, char *namep,
         char *descrp, unsigned int kind, char *fmtp, char *labelp);

     void
     SYSCTLINFO_HELPER_ALLWITHNEXT(void *buf, size_t idlevel, int *id,
         char *namep, char *descrp, unsigned int kind, char *fmtp,
         char *labelp, size_t idnextlevel, int *idnext);

     void
     SYSCTLINFO_HELPER_ALLWITHNEXTNAME(void *buf, size_t idlevel, int *id,
         char *namep, char *descrp, unsigned int kind, char *fmtp,
         char *labelp, char *namenextp);

DESCRIPTION
     Macros to wrap the sysctlinfo(4) interface to explore the sysctl tree and
     to get info about the nodes.  SYSCTLINFO() and SYSCLINFO_BYNAME() seek
     the node with id / idlevel or name, then the information specified by
     prop is copied into the buffer buf.  Before the call buflen gives the
     size of buf, after a successful call buflen gives the amount of data
     copied; the size of the info can be determined with the NULL argument for
     buf, the size will be returned in the location pointed to by buflen.  The
     value of prop[0] should be CTL_SYSCTL and prop[1] can specify the desired
     info, the possible values are listed later.

     SYSCTLINFO() accepts an array id of idlevel elements (between 1 and
     CTL_MAXNAME) and the following prop[1]:

     ENTRYFAKENAME
             if the node exists buf is set like a string with its name,
             otherwise sysctlinfo build a name depending on the id, e.g., with
             an id [1.1.100.500.1000] the name is "kern.ostype.100.500.1000".

     ENTRYNAME, ENTRYDESC, ENTRYLABEL and ENTRYFMT
             set buf like a string with the name, description, label and
             format, respectively.

     ENTRYKIND
             sets buf like an unsigned int with the kind of the node, its
             format is: 3 bytes for flags and 1 byte for type, they are
             defined in <sys/sysctl.h>.

     ENTRYNEXTNODE and ENTRYNEXTLEAF
             buf is set like an integer array with the id of the next
             node/leaf of a Depth-First Traversal, the next level is "buflen /
             sizeof(int)" to be consistent with the acceptable level range.

     ENTRYALLINFO
             sets the buf with all the info of the node, it should be passed
             to the helper macro SYSCTLINFO_HELPER_ALL(), if description,
             format or label is NULL, descp, fmtp or labep is set to ""
             respectively.

     ENTRYALLINFO_WITHNEXTNODE and ENTRYALLINFO_WITHNEXTLEAF
             set all the info of the node like SYSCTLINFO_ALLINFO with the
             next node/leaf, buf should be passed to
             SYSCTLINFO_HELPER_ALLWITHNEXT(), if the node has not a next
             idnextlevel is set to 0.

     SYSCTLINFO_BYNAME() accepts the following prop[1]:

     ENTRYFAKEIDBYNAME and ENTRYIDBYNAME
             buf is set like an integer array with the id of the node, the
             level is "buflen / sizeof(int)".  ENTRYFAKEIDBYNAME does not set
             the last level if its last level name is "", e.g., "n1.n2.n3."
             the id array is set to [1.2.3].

     ENTRYDESCBYNAME, ENTRYLABELBYNAME and ENTRYFMTBYNAME
             set buf like a string with the description, label and format
             respectively.

     ENTRYKINDBYNAME
             kind of an node, see ENTRYKIND.

     ENTRYALLINFOBYNAME
             sets the buf with all the info of the node, it should be passed
             to the helper macro SYSCTLINFO_HELPER_ALL(), if description,
             format or label is NULL, descp, fmtp or labep is set to ""
             respectively.

     ENTRYALLINFOBYNAME_WITHNEXTNODE and ENTRYALLINFOBYNAME_WITHNEXTLEAF
             set all the info of the node like SYSCTLINFO_ALLINFOBYNAME with
             the next node/leaf, buf should be passed to
             SYSCTLINFO_HELPER_ALLWITHNEXTNAME(), if the node has not a next
             node/leaf nextnamep is set to "".

IMPLEMENTATION NOTES
     The kernel provides an undocumented interface for the info of the sysctl
     tree, obviously sysctlinfo and the kernel interface can coexist.

     In "capability mode", see cap_enter(2), sysctlinfo checks if the node has
     the CTLFLAG_CAPRD or CTLFLAG_CAPWR flag before to return its info;
     sysctl(3) will check the "capability permission" to get or set a value.
     ENTRYFAKENAME has no capability check for compatibility with the kernel.
     ENTRYNEXTNODE and ENTRYNEXTLEAF check never the capability flags to
     traverse the tree also in capability mode.

     SYSCTLINFO() and SYSCTLINFO_BYNAME() seek the node with the id / idlevel
     or with the name then they share the same code.

RETURN VALUES
     The SYSCTLINFO() and SYSCTLINFO_BYNAME() functions return the value 0 if
     successful; otherwise the value -1 is returned and the global variable
     errno is set to indicate the error.

EXAMPLES
     If installed:
           /usr/local/share/examples/sysctlinfo/

     Example to visit the sysctl tree:

           int id[CTL_MAXNAME], *idp_unused, *idnextp;
           size_t idlevel, idnextlevel, buflen, i;
           char buf[BUFSIZE], *namep, *descrp, *fmtp, *labelp;
           unsigned int kind;
           int prop[2] = { CTL_SYSCTL, ENTRYALLINFO_WITHNEXTNODE };

           id[0]=0;
           idlevel=1;

           for (;;) {
                   for (i = 0; i < idlevel; i++)
                           printf("%d%c", id[i], i+1 < idlevel ? '.' : '\n');

                   buflen = BUFSIZE;
                   if(SYSCTLINFO(id, idlevel, prop, buf, &buflen) != 0) {
                           err(1, "ENTRYALLINFO_WITHNEXTNODE");

                   SYSCTLINFO_HELPER_ALLWITHNEXT(buf, idlevel, idp_unused, namep, descrp,
                                                 kind, fmtp, labelp, idnextlevel, idnextp);

                   printf("name: %s\n", namep);
                   printf("description: %s\n", descrp);
                   printf("label: %s\n", labelp);
                   printf("kind: %u\n", kind );
                   printf("flags: %u\n", kind & 0xfffffff0 );
                   printf("type: %u\n", kind & CTLTYPE );
                   printf("fmt: %s\n", fmtp);
                   printf("--------------------------------------\n");

                   if (idnextlevel < 1)
                           break;

                   memcpy(id, idnextp, idnextlevel * sizeof(int));
                   idlevel = idnextlevel;
           }

ERRORS
     The following errors may be reported:

     [ECAPMODE]         The node has not the CTLFLAG_CAPRD or CTLFLAG_CAPWR
                        flag in capability mode.

     [EINVAL]           name has more than CTL_MAXNAME levels.

     [EINVAL]           idlevel is either greater CTL_MAXNAME, equal to zero
                        or is not an integer.

     [ENAMETOOLONG]     name is >= MAXPATHLEN.

     [ENOATTR]          The node exists but its info is NULL.

     [ENOENT]           The node does not exist.

SEE ALSO
     cap_enter(2), sysctl(3), sysctlinfo(4)

HISTORY
     The sysctlinfo interface first appeared in FreeBSD 13.0.

AUTHORS
     The sysctlinfo interface was written by Alfonso S. Siciliano
     <alf.siciliano@gmail.com>

FreeBSD 13.0-CURRENT          September 20, 2019          FreeBSD 13.0-CURRENT

sysctlview 1.0

2019-04-12T18:00:00+00:00

sysctlview 1.0 has been released!

sysctlview is a graphical explorer for the sysctl MIB (Source Code - Port - Distrowatch - DiscoverBSD).

To install the port:

# cd /usr/ports/deskutils/sysctlview/ && make install clean

To add the package:

# pkg install sysctlview