DragonFly On-Line Manual Pages

Search: Section:  

sg_intro(3)                                                        sg_intro(3)


NAME

       sg_intro - get system statistics


SYNOPSIS

       #include <statgrab.h>


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
       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) and sg_get_STATTYPE_r
       (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 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().  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 doesn't 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 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(), it's 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_drop_privileges() return SG_ERROR_NONE
       on success, and any other on failure.

       For proper thread support, sg_lock_mutex() and 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 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

       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 sg_get_error() 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

       <http://www.i-scream.org/libstatgrab/>

i-scream                          2013-06-07                       sg_intro(3)

Search: Section: