sg_intro — get system statistics
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
sg_get_nelements(). 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
sg_get_cpu_stats_r). The difference between both
interfaces is the ownership of the returned statistic structures: while
the (well known)
sg_get_cpu_stats returns a
pointer to a memory area owned and controlled by the statgrab library,
sg_get_cpu_stats_r 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.
sg_init() 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
sg_init() 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
sg_init() 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
discards setuid and setgid privileges, immediately after you call
sg_init(), unless your application has a reason
for needing setuid or setgid privileges.
sg_shutdown() 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
sg_shutdown() 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.
SG_ERROR_NONE on success, and any other on
For proper thread support,
sg_unlock_mutex() 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
utmp. 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
sg_init() to prevent
first call to
sg_shutdown() leaves the library
in an unusable status).
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.
sg_get_error() and associates to get
informed about the individual circumstances of the error condition.