1sg_get_mem_stats(3)                                        sg_get_mem_stats(3)
2
3
4

NAME

6       sg_get_mem_stats,         sg_get_mem_stats_r,        sg_free_mem_stats,
7       sg_get_swap_stats, sg_get_swap_stats_r,  sg_free_swap_stats  -  get  VM
8       statistics
9

SYNOPSIS

11       #include <statgrab.h>
12
13
14       sg_mem_stats *sg_get_mem_stats (size_t *entries);
15
16       sg_mem_stats *sg_get_mem_stats_r (size_t *entries);
17
18       sg_error sg_free_mem_stats (sg_mem_stats *data);
19
20       sg_swap_stats *sg_get_swap_stats (size_t *entries);
21
22       sg_swap_stats *sg_get_swap_stats_r (size_t *entries);
23
24       sg_error sg_free_swap_stats (sg_swap_stats *data);
25

DESCRIPTION

27       Memory  statistics are accessed through the sg_get_mem_stats() function
28       and the sg_get_mem_stats_r() function.  Both  return  a  pointer  to  a
29       sg_mem_stats  buffer.  Note that this statistic doesn't need to map the
30       entire physical memory usage, it represents the real memory  usable  by
31       the operating system.
32
33       Memory statistics are accessed through the sg_get_swap_stats() function
34       and the sg_get_swap_stats_r() function. Both  return  a  pointer  to  a
35       sg_swap_stats buffer.
36
37       API Shortcut
38
39       ┌────────────────────┬─────────────────┬─────────────────────┐
40       │function            │ returns         │ data owner          │
41       ├────────────────────┼─────────────────┼─────────────────────┤
42       │sg_get_mem_stats    │ sg_mem_stats *  │ libstatgrab (thread │
43       │                    │                 │ local)              │
44       ├────────────────────┼─────────────────┼─────────────────────┤
45       │sg_get_mem_stats_r  │ sg_mem_stats *  │ caller              │
46       ├────────────────────┼─────────────────┼─────────────────────┤
47       │sg_get_swap_stats   │ sg_swap_stats * │ libstatgrab (thread │
48       │                    │                 │ local)              │
49       ├────────────────────┼─────────────────┼─────────────────────┤
50       │sg_get_swap_stats_r │ sg_swap_stats * │ caller              │
51       └────────────────────┴─────────────────┴─────────────────────┘
52       The  sg_mem_stats  buffer  received  from  sg_get_mem_stats_r() and the
53       sg_swap_stats buffer received from sg_get_swap_stats_r() must be  freed
54       using  sg_free_mem_stats()  or  the sg_free_swap_stats(), respectively,
55       when not needed any more. The caller is responsible for doing it.
56
57       On the FreeBSD operating system elevated privileges are required to ac‐
58       cess the swap statistics. Making the program setgid kmem should be suf‐
59       ficient. Programs running as root will not have this problem.
60

RETURN VALUES

62       The VM system calls can return a pointer to either a sg_mem_stats or  a
63       sg_swap_stats.
64
65       typedef struct{
66               unsigned long long total;
67               unsigned long long free;
68               unsigned long long used;
69               unsigned long long cache;
70               time_t systime;
71       } sg_mem_stats;
72
73
74       total  The total amount of real memory in bytes.
75
76       free   The free amount of real memory in bytes.
77
78       used   The used amount of real memory in bytes.
79
80       cache  The amount of real memory in bytes used for caching.
81
82       systime
83              the  timestamp  when  the above stats where collected in seconds
84              since epoch
85
86       typedef struct {
87               unsigned long long total;
88               unsigned long long used;
89               unsigned long long free;
90               time_t systime;
91       } sg_swap_stats;
92
93
94       total  The total swap space in bytes.
95
96       used   The used swap in bytes.
97
98       free   The free swap in bytes.
99
100       systime
101              The timestamp when the above stats where  collected  in  seconds
102              since epoch
103

TODO

105       Add  a  function  to hold open the file descriptor to the kernel memory
106       structures. Doing this  would  allow  the  elevated  privileges  to  be
107       dropped early on.
108

SEE ALSO

110       statgrab(3)
111

WEBSITE

113       ⟨http://www.i-scream.org/libstatgrab/⟩
114
115
116
117i-scream                          2013-06-17               sg_get_mem_stats(3)