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

FC#include <statgrab.h>F[0]

FCsg_mem_stats *sg_get_mem_statsF[0] FC(size_t *entries);F[0]

FCsg_mem_stats *sg_get_mem_stats_rF[0] FC(size_t *entries);F[0]

FCsg_error sg_free_mem_statsF[0] FC(sg_mem_stats *data);F[0]

FCsg_swap_stats *sg_get_swap_statsF[0] FC(size_t *entries);F[0]

FCsg_swap_stats *sg_get_swap_stats_rF[0] FC(size_t *entries);F[0]

FCsg_error sg_free_swap_statsF[0] FC(sg_swap_stats *data);F[0]

DESCRIPTION

Memory statistics are accessed through the FCsg_get_mem_statsF[0]() function and the FCsg_get_mem_stats_rF[0]() function. Both return a pointer to a FCsg_mem_statsF[0] 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 FCsg_get_swap_statsF[0]() function and the FCsg_get_swap_stats_rF[0]() function. Both return a pointer to a FCsg_swap_statsF[0] buffer.

API Shortcut

function	returns	data owner
sg_get_mem_stats	FCsg_mem_statsF[0] *	libstatgrab (thread local)
sg_get_mem_stats_r	FCsg_mem_statsF[0] *	caller
sg_get_swap_stats	FCsg_swap_statsF[0] *	libstatgrab (thread local)
sg_get_swap_stats_r	FCsg_swap_statsF[0] *	caller

The FCsg_mem_statsF[0] buffer received from FCsg_get_mem_stats_rF[0]() and the FCsg_swap_statsF[0] buffer received from FCsg_get_swap_stats_rF[0]() must be freed using FCsg_free_mem_statsF[0]() or the FCsg_free_swap_statsF[0](), 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 FCsg_mem_statsF[0] or a FCsg_swap_statsF[0].

FC
typedef struct{
        unsigned long long total;
        unsigned long long free;
        unsigned long long used;
        unsigned long long cache;
        time_t systime;
} sg_mem_stats;
    F[0]

FCtotalF[0]: The total amount of real memory in bytes.

FCfreeF[0]: The free amount of real memory in bytes.

FCusedF[0]: The used amount of real memory in bytes.

FCcacheF[0]: The amount of real memory in bytes used for caching.

FCsystimeF[0]: the timestamp when the above stats where collected in seconds since epoch

FC
typedef struct {
        unsigned long long total;
        unsigned long long used;
        unsigned long long free;
        time_t systime;
} sg_swap_stats;
    F[0]

FCtotalF[0]: The total swap space in bytes.

FCusedF[0]: The used swap in bytes.

FCfreeF[0]: The free swap in bytes.

FCsystimeF[0]: 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.

WEBSITE

⟨https://libstatgrab.org/⟩