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/⟩