libsysctl: a C API for sysctl-mib-tree

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

libsysctl: a C API for sysctl-mib-tree

Alfonso Sabato 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

_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: libsysctl: a C API for sysctl-mib-tree

Ed Schouten-6
Hi Alfonso,

Op za 22 dec. 2018 om 20:26 schreef Alfonso Siciliano <[hidden email]>:
> 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.

Great work! This would have been nice to have when I implemented the
Prometheus metrics exporter for sysctl:

https://svnweb.freebsd.org/base/head/usr.sbin/prometheus_sysctl_exporter/prometheus_sysctl_exporter.c?view=markup

Best regards,
--
Ed Schouten <[hidden email]>
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: libsysctl: a C API for sysctl-mib-tree

Alfonso Sabato Siciliano
Hi Ed,

> Ed Schouten <[hidden email]> wrote:
> > Alfonso Siciliano <[hidden email]>:
> > 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.
>
> Great work!

Thanks

> This would have been nice to have when I implemented the
> Prometheus metrics exporter for sysctl:
>
> https://svnweb.freebsd.org/base/head/usr.sbin/prometheus_sysctl_exporter/prometheus_sysctl_exporter.c?view=markup

I thought libsysctl exactly to help to write programs like "prometheus_sysctl_exporter"

Regards,
Alfonso

---
Alfonso S. Siciliano
   http://alfix.gitlab.io
_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"
Reply | Threaded
Open this post in threaded view
|

Re: libsysctl: a C API for sysctl-mib-tree

Alfonso Sabato Siciliano
In reply to this post by Alfonso Sabato Siciliano
Hello,

> 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.

> I could submit a patch to reviews.freebsd.org to solicit feedback

Review: https://reviews.freebsd.org/D18696 (reviewers are welcome)

> and write a wiki page.

Wiki: https://wiki.freebsd.org/AlfonsoSiciliano/libsysctl


> Overview  http://gitlab.com/alfix/libsysctl/blob/master/README.md
> manuals *.3 in libsysctl/doc/ are 'work in progress'.

Manual: https://gitlab.com/alfix/libsysctl/blob/master/libsysctl.txt


Regards,
Alfonso Siciliano


_______________________________________________
[hidden email] mailing list
https://lists.freebsd.org/mailman/listinfo/freebsd-hackers
To unsubscribe, send any mail to "[hidden email]"