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

       ⟨https://libstatgrab.org/⟩