Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  parame-
       ter  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  So-
       laris it	reads the device mappings that in some cases are only accessi-
       ble 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. Re-
       gardless	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 applica-
       tion 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 ex-
       isting which had	made calls to the statgrab library. If you  don't  in-
       voke sg_shutdown(), it's	done automatically at_exit().

       Both, sg_init() and sg_shutdown() use a counter to prevent to early de-
       struction of libstatgrab	in a process where more	than one component us-
       es 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 pro-
       tect  known unsafe functions. There's currently one system API known to
       be not thread-safe: accessing utmp. The other non-threadsafe  function-
       ality  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 unus-
       able 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  in-
       dividual	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_net-
       work_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)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | WEBSITE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sg_intro&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help