1sg_intro(3) sg_intro(3)
2
6 sg_intro - get system statistics
7
9 #include <statgrab.h>
10
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 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 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 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 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 sg_init(), sg_shutdown() and sg_drop_privileges() return SG_ERROR_NONE
65 on success, and any other on failure.
66 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 Mutex name: statgrab
79 Protects: statgrab library globals
80 Mutex name: utmp
82 Protects: accessing login records
83 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 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
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
102 ⟨https://libstatgrab.org/⟩
103libstatgrab 2019-03-08 sg_intro(3)