libsysctl: a C API for sysctl-mib-tree

[Alfonso Siciliano]

Hey!

I' m currently working on a library called "libsysctl" which will
provide a C API to wrap kern_sysctl.c undocumented interface, build
mib-entry, entries-list and mib-tree in userspace and then to do 
the work that /sbin/sysctl currently does. 
This project started from a wish to write a "sysctl-table" tool 
(like "top" and "htop" for processes), examples below, so 
I need to have info about kernel sysctl-mib-tree.

The advantages to have libsysctl are: an easy userspace API to the
kernel sysctl-mib-tree, building quickly a custom sysctl(8) tool
and changes to kern_sysctl.c interface won't upset userspace tools.

I am coding on my pc: FreeBSD 13.0-CURRENT amd64 and src are in
   http://gitlab.com/alfix/libsysctl [0]

I could submit a patch to reviews.freebsd.org to solicit feedback and 
write a wiki page.
The README.md [2] shows every function and links to examples [1], 
anyway the following API overview has extras notes.

-- API Overview --

Implementation note: the following functions call sysctl(2) for
                     wrapping 0.[1-6] entries/'kernel state'. 
                     Kernel returns only next leaf, nextnode() needs
                     extra computation

/*  'undocumented kern_sysctl.c API' wrap functions  
 *  return: 0 for success, negative value for failure.    */

libsysctl_nametoid(), libsysctl_name(), libsysctl_desc(),
libsysctl_label(), libsysctl_info(), libsysctl_nextnode(),
libsysctl_next() and libsysctl_nextleaf();

... EXTRA MACROS ...

Note: I prefer to use the following functions:

/* "struct libsysctl_object" functions 
 *    return: NULL for failure, pointer to heap for success. */

Note: 
 - The following functions use previous functions plus SLIST macros.
 - "struct libsysctl_object" is a mib-entry in userspace, 
   it is handier than kernel sysctl_oid <sys/sysctl.h>.
 - libsysctl_object() and libsysctl_tree() are "conceptually similar"
   to NetBSD sysctlgetmibinfo().
 - libsysctl_grouplist() returns a "linear" tree.
 - libsysctl_tree() sets .childs so it builds an userspace mib-tree, 
   it is useful to make a custom sysctl tool; I like it :-) .
 - libsysctl_free*() functions free the heap.

SLIST_HEAD(libsysctl_object_list, libsysctl_object);

struct libsysctl_object {
               ...
               int *id;
               size_t idlen;
               char *name;
               char *desc;
               char *label;
               uint8_t type;
               uint32_t flags;
               char *fmt;
               struct libsysctl_object_list *childs;
               ...
};

Note: OR_FLAGS are just the object' s fields to set.

struct libsysctl_object *
libsysctl_object(id, idlen, OR_FLAGS);

struct libsysctl_object_list *
libsysctl_filterlist(libsysctl_filterfunc_t *, OR_FLAGS); 

struct libsysctl_object_list *
libsysctl_grouplist(id, idlen, OR_FLAGS, max_depth); 

struct libsysctl_object *
libsysctl_tree(id, idlen, OR_FLAGS, max_edges);

libsysctl_freeobject(), libsysctl_freelist() and libsysctl_freetree().



--- Docs ---

Files *.c in libsysctl/examples/ show every function. [1]
Overview  http://gitlab.com/alfix/libsysctl/blob/master/README.md [2]
manuals *.3 in libsysctl/doc/ are 'work in progress'.



--- Tools using libsysctl ---

- "sysctlview 0.1", a sysctl gtk gui tool,
  http://gitlab.com/alfix/sysctlview [3]

- "nsysctl 0.1", sysctl(8) + [-FIlMmSy] + [--libxo],
  http://gitlab.com/alfix/nsysctl [4]



I appreciate any feedback that you can give me.


Regards,
Alfonso S. Siciliano 
wiki.freebsd.org/AlfonsoSiciliano


LINKS
[0] git repo:  http://gitlab.com/alfix/libsysctl 
[1] examples:  http://gitlab.com/alfix/libsysctl/examples
[2] README.md: http://gitlab.com/alfix/libsysctl/blob/master/README.md
[3] sysctlview http://gitlab.com/alfix/sysctlview
[4] nsysctl:   http://gitlab.com/alfix/nsysctl