1sg_intro(3)                                                        sg_intro(3)
2
3
4

NAME

6       sg_intro - get system statistics
7

SYNOPSIS

9       #include <statgrab.h>
10
11

DESCRIPTION

13       The  statgrab  library  provides  a cross-platform interface to getting
14       system statistics. Each of the function calls to grab  some  statistics
15       returns  an  array of structures. Functions which return always a fixed
16       number of array entries (typical one) won't take an additional  parame‐
17       ter  to  store the number of array entries, others will. Anyway, if the
18       information isn't available anymore, you can  call  sg_get_nelements().
19       See  the  manual  page for each individual function for more details on
20       usage.
21
22       For each statistic type there are two functions available to fetch  the
23       data:  sg_get_STATTYPE  (e.g.   sg_get_cpu_stats) and sg_get_STATTYPE_r
24       (e.g.  sg_get_cpu_stats_r). The difference between both  interfaces  is
25       the  ownership  of  the  returned statistic structures: while the (well
26       known) sg_get_cpu_stats returns a pointer to a memory  area  owned  and
27       controlled  by  the  statgrab library, sg_get_cpu_stats_r will return a
28       pointer to a memory area owned and controlled by the  caller.   Storage
29       owned  by the statgrab library will be reused in follow-up calls to the
30       same statistic grabbing function within the same thread. The memory  is
31       freed when the thread ends. This could result in dangling pointers when
32       you exchange those pointers between threads. Storage which is owned  by
33       the caller must be freed by the caller when it's not used any more.
34
35       sg_init()  must  be the first function you call before you start to use
36       libstatgrab; it performs all  the  one-time  initialisation  operations
37       that  need  setuid/setgid  privileges. For instance, on *BSD it opens a
38       descriptor to be able to read kernel structures later on,  and  on  So‐
39       laris it reads the device mappings that in some cases are only accessi‐
40       ble by root (machines with a /dev/osa).  To handle this, each  statgrab
41       module  has  a  private  initialisation  routine  called  by sg_init().
42       sg_init() takes an argument to tell whether  initialisation  errors  of
43       components  shall  abort the library initialisation process or not. Re‐
44       gardless of this value, the failing module initialisations will usually
45       lead into (partially) unusable statistics. Once sg_init() has run, most
46       of the other libstatgrab functions no longer need  elevated  privileges
47       (some  Unices require higher privileges to access command line argument
48       of processes owned by other users, Linux doesn't deliver  some  network
49       card  information  to unprivileged users, etc.). It is therefore a good
50       idea to call sg_drop_privileges(), which  discards  setuid  and  setgid
51       privileges,  immediately after you call sg_init(), unless your applica‐
52       tion has a reason for needing setuid or setgid privileges.
53
54       sg_shutdown() should be the very last  statgrab  library  function  you
55       call.  You  shouldn't invoke this function when any thread is still ex‐
56       isting which had made calls to the statgrab library. If you  don't  in‐
57       voke sg_shutdown(), it's done automatically at_exit().
58
59       Both, sg_init() and sg_shutdown() use a counter to prevent to early de‐
60       struction of libstatgrab in a process where more than one component us‐
61       es libstatgrab. This counter is guarded by a mutual exclusion semaphore
62       when thread capabilities are built in.
63
64       sg_init(), sg_shutdown() and sg_drop_privileges() return  SG_ERROR_NONE
65       on success, and any other on failure.
66
67       For  proper  thread  support, sg_lock_mutex() and sg_unlock_mutex() are
68       available to allow locking system functions which aren't  thread  safe.
69       While  it's  generally not the wisest idea to mix calls to the statgrab
70       library and similar calls to the system library, it is possible to pro‐
71       tect  known unsafe functions. There's currently one system API known to
72       be not thread-safe: accessing utmp. The other non-threadsafe  function‐
73       ality  used  by the statgrab library is the global component management
74       during initialisation (e.g. counting the number of calls  to  sg_init()
75       to  prevent  first call to sg_shutdown() leaves the library in an unus‐
76       able status).
77
78       Mutex name: statgrab
79       Protects: statgrab library globals
80
81       Mutex name: utmp
82       Protects: accessing login records
83
84       There's currently no way to get a list of used mutex names, so beg that
85       any  author which adds more semaphores to guard implementations is fair
86       enough to add them here.
87
88       It is the intended practice that whenever  a  libstatgrab  function  is
89       called  and  subsequently  fails that an appropriate error will be set.
90       Please use sg_get_error() and associates to get informed about the  in‐
91       dividual circumstances of the error condition.
92

SEE ALSO

94       libstatgrab(3)        sg_get_cpu_stats(3)       sg_get_disk_io_stats(3)
95       sg_get_fs_stats(3)       sg_get_host_info(3)       sg_get_load_stats(3)
96       sg_get_mem_stats(3)        sg_get_network_io_stats(3)       sg_get_net‐
97       work_iface_stats(3)    sg_get_page_stats(3)     sg_get_process_stats(3)
98       sg_get_swap_stats(3)  sg_get_user_stats(3) sg_get_error(3) sg_internal-
99       intro(3)
100

WEBSITE

102http://www.i-scream.org/libstatgrab/
103
104
105
106i-scream                          2013-06-07                       sg_intro(3)
Impressum