sg_intro(3)

NAME
sg_intro - get system statistics

SYNOPSIS
\FC#include <statgrab.h>\F[]

DESCRIPTION
The statgrab library provides a cross-platform interface to getting system statistics. Each of the function calls to grab some statistics returns an array of structures. Functions which return always a fixed number of array entries (typical one) won't take an additional parameter to store the number of array entries, others will. Anyway, if the information isn't available anymore, you can call \FCsg_get_nelements\F[](). See the manual page for each individual function for more details on usage.

For each statistic type there are two functions available to fetch the data: \FCsg_get_STATTYPE\F[] (e.g. \FCsg_get_cpu_stats\F[]) and \FCsg_get_STATTYPE_r\F[] (e.g. \FCsg_get_cpu_stats_r\F[]). The difference between both interfaces is the ownership of the returned statistic structures: while the (well known) \FCsg_get_cpu_stats\F[] returns a pointer to a memory area owned and controlled by the statgrab library, \FCsg_get_cpu_stats_r\F[] will return a pointer to a memory area owned and controlled by the caller. Storage owned by the statgrab library will be reused in follow-up calls to the same statistic grabbing function within the same thread. The memory is freed when the thread ends. This could result in dangling pointers when you exchange those pointers between threads. Storage which is owned by the caller must be freed by the caller when it's not used any more.

\FCsg_init\F[]() must be the first function you call before you start to use libstatgrab; it performs all the one-time initialisation operations that need setuid/setgid privileges. For instance, on *BSD it opens a descriptor to be able to read kernel structures later on, and on Solaris it reads the device mappings that in some cases are only accessible by root (machines with a /dev/osa). To handle this, each statgrab module has a private initialisation routine called by \FCsg_init\F[](). \FCsg_init\F[]() takes an argument to tell whether initialisation errors of components shall abort the library initialisation process or not. Regardless of this value, the failing module initialisations will usually lead into (partially) unusable statistics. Once \FCsg_init\F[]() has run, most of the other libstatgrab functions no longer need elevated privileges (some Unices require higher privileges to access command line argument of processes owned by other users, Linux doesn't deliver some network card information to unprivileged users, etc.). It is therefore a good idea to call \FCsg_drop_privileges\F[](), which discards setuid and setgid privileges, immediately after you call \FCsg_init\F[](), unless your application has a reason for needing setuid or setgid privileges.

\FCsg_shutdown\F[]() should be the very last statgrab library function you call. You shouldn't invoke this function when any thread is still existing which had made calls to the statgrab library. If you don't invoke \FCsg_shutdown\F[](), it's done automatically \FCat_exit\F[]().

Both, \FCsg_init\F[]() and \FCsg_shutdown\F[]() use a counter to prevent to early destruction of libstatgrab in a process where more than one component uses libstatgrab. This counter is guarded by a mutual exclusion semaphore when thread capabilities are built in.

\FCsg_init\F[](), \FCsg_shutdown\F[]() and \FCsg_drop_privileges\F[]() return SG_ERROR_NONE on success, and any other on failure.

For proper thread support, \FCsg_lock_mutex\F[]() and \FCsg_unlock_mutex\F[]() are available to allow locking system functions which aren't thread safe. While it's generally not the wisest idea to mix calls to the statgrab library and similar calls to the system library, it is possible to protect known unsafe functions. There's currently one system API known to be not thread-safe: accessing \FCutmp\F[]. The other non-threadsafe functionality used by the statgrab library is the global component management during initialisation (e.g. counting the number of calls to \FCsg_init\F[]() to prevent first call to \FCsg_shutdown\F[]() leaves the library in an unusable status).

Mutex name: statgrab
Protects: statgrab library globals

Mutex name: utmp
Protects: accessing login records

There's currently no way to get a list of used mutex names, so beg that any author which adds more semaphores to guard implementations is fair enough to add them here.

It is the intended practice that whenever a libstatgrab function is called and subsequently fails that an appropriate error will be set. Please use \FCsg_get_error\F[]() and associates to get informed about the individual circumstances of the error condition.

SEE ALSO
libstatgrab(3) sg_get_cpu_stats(3) sg_get_disk_io_stats(3) sg_get_fs_stats(3) sg_get_host_info(3) sg_get_load_stats(3) sg_get_mem_stats(3) sg_get_network_io_stats(3) sg_get_network_iface_stats(3) sg_get_page_stats(3) sg_get_process_stats(3) sg_get_swap_stats(3) sg_get_user_stats(3) sg_get_error(3) sg_internal-intro(3)

WEBSITE
⟨https://libstatgrab.org/⟩