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) wont take an additional
parameter to store the number of array entries, others will. Anyway,
if the information isnt 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
data: sg_get_STATTYPE (e.g.
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 its
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().
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
statistics. Once 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 doesnt deliver some network
card information to unprivileged users, etc.). It is therefore a
good idea to call sg_drop_privileges(), which
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 shouldnt invoke this function when
any thread is still existing which had made calls to the statgrab
library. If you dont invoke sg_shutdown(), its
done automatically at_exit().
Both, sg_init() and
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_init(), sg_shutdown() and
SG_ERROR_NONE on success, and any other on
For proper thread support, sg_lock_mutex() and
sg_unlock_mutex() are available to allow locking
system functions which arent thread safe. While its 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. Theres currently one system API known to be not
thread-safe: accessing 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).
Mutex name: statgrab
Protects: statgrab library globals
Mutex name: utmp
Protects: accessing login records
Theres 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 sg_get_error() and associates to get
informed about the individual circumstances of the error condition.