NAME

       sg_get_mem_stats,      sg_get_mem_stats_r,      sg_free_mem_stats,      sg_get_swap_stats,
       sg_get_swap_stats_r, sg_free_swap_stats - get VM statistics

SYNOPSIS

       #include <statgrab.h>

       sg_mem_stats *sg_get_mem_stats (size_t *entries);

       sg_mem_stats *sg_get_mem_stats_r (size_t *entries);

       sg_error sg_free_mem_stats (sg_mem_stats *data);

       sg_swap_stats *sg_get_swap_stats (size_t *entries);

       sg_swap_stats *sg_get_swap_stats_r (size_t *entries);

       sg_error sg_free_swap_stats (sg_swap_stats *data);

DESCRIPTION

       Memory  statistics  are  accessed  through  the  sg_get_mem_stats()   function   and   the
       sg_get_mem_stats_r()  function. Both return a pointer to a sg_mem_stats buffer.  Note that
       this statistic doesn't need to map the entire physical memory  usage,  it  represents  the
       real memory usable by the operating system.

       Memory   statistics   are  accessed  through  the  sg_get_swap_stats()  function  and  the
       sg_get_swap_stats_r() function. Both return a pointer to a sg_swap_stats buffer.

       API Shortcut

       ┌────────────────────┬─────────────────┬──────────────────────────┐
       │function            │ returns         │ data owner               │
       ├────────────────────┼─────────────────┼──────────────────────────┤
       │sg_get_mem_stats    │ sg_mem_stats *  │ libstatgrab      (thread │
       │                    │                 │ local)                   │
       ├────────────────────┼─────────────────┼──────────────────────────┤
       │sg_get_mem_stats_r  │ sg_mem_stats *  │ caller                   │
       ├────────────────────┼─────────────────┼──────────────────────────┤
       │sg_get_swap_stats   │ sg_swap_stats * │ libstatgrab      (thread │
       │                    │                 │ local)                   │
       ├────────────────────┼─────────────────┼──────────────────────────┤
       │sg_get_swap_stats_r │ sg_swap_stats * │ caller                   │
       └────────────────────┴─────────────────┴──────────────────────────┘
       The sg_mem_stats buffer received from sg_get_mem_stats_r() and  the  sg_swap_stats  buffer
       received  from  sg_get_swap_stats_r()  must  be  freed  using  sg_free_mem_stats()  or the
       sg_free_swap_stats(), respectively, when not needed any more. The  caller  is  responsible
       for doing it.

       On  the  FreeBSD  operating  system  elevated  privileges  are required to access the swap
       statistics. Making the program setgid kmem should be sufficient. Programs running as  root
       will not have this problem.

RETURN VALUES

       The VM system calls can return a pointer to either a sg_mem_stats or a sg_swap_stats.

       typedef struct{
               unsigned long long total;
               unsigned long long free;
               unsigned long long used;
               unsigned long long cache;
               time_t systime;
       } sg_mem_stats;

       total  The total amount of real memory in bytes.

       free   The free amount of real memory in bytes.

       used   The used amount of real memory in bytes.

       cache  The amount of real memory in bytes used for caching.

       systime
              the timestamp when the above stats where collected in seconds since epoch

       typedef struct {
               unsigned long long total;
               unsigned long long used;
               unsigned long long free;
               time_t systime;
       } sg_swap_stats;

       total  The total swap space in bytes.

       used   The used swap in bytes.

       free   The free swap in bytes.

       systime
              The timestamp when the above stats where collected in seconds since epoch

TODO

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

SEE ALSO

       statgrab(3)

WEBSITE

       ⟨https://libstatgrab.org/⟩