DragonFly On-Line Manual Pages

sg_get_mem_stats(3)                                        sg_get_mem_stats(3)

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
       <http://www.i-scream.org/libstatgrab/>

i-scream                          2013-06-17               sg_get_mem_stats(3)