Provided by: libstatgrab-dev_0.92.1-1.2build1_amd64 
NAME
sg_get_fs_stats, sg_get_fs_stats_r, sg_get_fs_stats_diff, sg_get_fs_stats_diff_between,
sg_free_fs_stats, sg_get_valid_filesystems, sg_set_valid_filesystems,
sg_fs_compare_device_name, sg_fs_compare_mnt_point - get file system statistics
SYNOPSIS
#include <statgrab.h>
sg_fs_stats *sg_get_fs_stats (size_t *entries);
sg_fs_stats *sg_get_fs_stats_r (size_t *entries);
sg_fs_stats *sg_get_fs_stats_diff (size_t *entries);
sg_fs_stats *sg_get_fs_stats_diff_between (const sg_fs_stats *cur, const sg_fs_stats
*last, size_t *entries);
sg_error sg_free_fs_stats (sg_fs_stats *data);
const char **sg_get_valid_filesystems (size_t *entries);
sg_error sg_set_valid_filesystems (const char *valid_fs[]);
int sg_fs_compare_device_name (const void *va, const void *vb);
int sg_fs_compare_mnt_point (const void *va, const void *vb);
DESCRIPTION
The sg_get_fs_stats functions provide statistics of mounted file systems. Both functions
take an optional entries parameter, which points (when given) to a size_t to take the
number of returned vector entries.
The sg_get_fs_stats() and sg_get_fs_stats_r() functions deliver the file system statistics
of the moment the function is called. The sg_get_fs_stats_diff() and
sg_get_fs_stats_diff_between() deliver the difference between two calls of
sg_get_fs_stats() or sg_get_fs_stats_r(), respectively.
API Shortcut
┌─────────────────────────────┬───────────────┬──────────────────────────┐
│function │ returns │ data owner │
├─────────────────────────────┼───────────────┼──────────────────────────┤
│sg_get_fs_stats │ sg_fs_stats * │ libstatgrab (thread │
│ │ │ local) │
├─────────────────────────────┼───────────────┼──────────────────────────┤
│sg_get_fs_stats_r │ sg_fs_stats * │ caller │
├─────────────────────────────┼───────────────┼──────────────────────────┤
│sg_get_fs_stats_diff │ sg_fs_stats * │ libstatgrab (thread │
│ │ │ local) │
├─────────────────────────────┼───────────────┼──────────────────────────┤
│sg_get_fs_stats_diff_between │ sg_fs_stats * │ caller │
├─────────────────────────────┼───────────────┼──────────────────────────┤
│sg_get_valid_filesystems │ char ** │ libstatgrab (global) │
└─────────────────────────────┴───────────────┴──────────────────────────┘
The sg_fs_stats vectors received from sg_get_fs_stats_r() or
sg_get_fs_stats_diff_between() must be freed using sg_free_fs_stats() when not needed
anymore. The caller is responsible for doing it.
The statgrab library comes with a built-in list of valid file system types depending on
the operating system it was compiled for. Some operating systems additionally provide an
API to learn the file system types known or valid to the running OS instance, which is
used when detected. Nevertheless there are known problems when collecting file system
statistics: network file systems are mounted from delaunched servers, file system
developers run an experimental driver etc.
To prevent processes hang in getting file system statistics or allow developers to test
their drivers, the processes may modify the list of valid file systems using the
sg_get_valid_filesystems() and the sg_set_valid_filesystems(). The list of char *
parameters both functions work with is always finished with an element pointing to NULL.
The returned list of sg_get_valid_filesystems() must not be modified. Always copy the
list into an own structure, if you plan to extend or reduce the list:
Remove Network FS Example
int compare_fs_type(const void *va, const void *vb) {
const char **a = (const char **)va;
const char **b = (const char **)vb;
return strcmp( *a, *b );
}
void filter_network_fs_types(void) {
/* known network file system names on different platforms */
const char *nfs_types[] = { "nfs", "nfs3", "nfs4", "cifs", "smbfs", "samba" };
const size_t nfs_types_count = sizeof(nfs_types) / sizeof(nfs_types[0])
size_t fs_entries = 0;
const char **orig_valid_fs = sg_get_valid_filesystems(&fs_entries);
/* duplicate into own memory to modify list */
char **valid_fs = calloc( entries + 1, sizeof(valid_fs[0]) );
memcpy( valid_fs, orig_valid_fs, (entries + 1) * sizeof(valid_fs[0]) );
size_t i;
for( i = 0; i < nfs_types_count; ++i ) {
char **inv_fs = bsearch( &nfs_types[i], &valid_fs[0],
fs_entries, sizeof(valid_fs[0]),
compare_fs_type );
if( NULL != inv_fs ) {
/* copy including trailing NULL pointer */
memmove( inv_fs, inv_fs + 1, fs_entries - (inv_fs - valid_fs) );
--fs_entries;
}
}
sg_set_valid_filesystems( valid_fs );
free( valid_fs );
}
Note that there's no need to duplicate the strings contained in the list of valid file
systems in the above example - they aren't modified.
The list returned by sg_get_valid_filesystems() might become invalid when used while the
process makes calls to sg_set_valid_filesystems(). None of the sg_fs_stats functions
protect the access to the globally used storage where the own copy of the list of the
valid file systems is held. It's the responsibility of the caller not to mix configuration
calls with calls to fetch statistics.
Additionally two support functions for qsort(3) are available: sg_fs_compare_device_name()
and sg_fs_compare_mnt_point().
Sort Example
size_t entries;
sg_fs_stats *fs_stats = NULL;
while( NULL != ( fs_stats = sg_get_fs_stats_diff(&entries) ) ) {
/* order entries alphabetically using the mountpoint */
qsort( fs_stats, entries, sizeof(fs_stats[0]), &sg_fs_compare_mnt_point );
show_fs_stats( fs_stats );
}
RETURN VALUES
sg_get_fs_stats returns a pointer to a structure of type sg_fs_stats.
typedef enum {
sg_fs_unknown = 0,
sg_fs_regular = 1 << 0,
sg_fs_special = 1 << 1,
sg_fs_loopback = 1 << 2,
sg_fs_remote = 1 << 3,
sg_fs_local = (sg_fs_regular | sg_fs_special),
sg_fs_alltypes = (sg_fs_regular | sg_fs_special | sg_fs_loopback | sg_fs_remote)
} sg_fs_device_type;
typedef struct {
char *device_name;
char *fs_type;
char *mnt_point;
sg_fs_device_type device_type;
unsigned long long size;
unsigned long long used;
unsigned long long free;
unsigned long long avail;
unsigned long long total_inodes;
unsigned long long used_inodes;
unsigned long long free_inodes;
unsigned long long avail_inodes;
unsigned long long io_size;
unsigned long long block_size;
unsigned long long total_blocks;
unsigned long long free_blocks;
unsigned long long used_blocks;
unsigned long long avail_blocks;
time_t systime;
} sg_fs_stats;
device_name
The name known to the operating system. (eg. on linux it might be hda)
fs_type
The file system type of the file system (eg. hpfs or ufs).
mnt_point
The mount point at which the file system is mounted.
device_type
The device type of the file system, currently not filled and always sg_fs_unknown.
size The total size, in bytes, of the file system.
size = used + free
used The amount of space, in bytes, used on the file system.
avail The amount of space, in bytes, available on the file system for non-privileged
users/processes (free space less reserved space).
avail = free - reserved
free The amount of space, in bytes, free on the file system.
total_inodes
The total number of inodes in the file system.
used_inodes
The number of used inodes in the file system.
free_inodes
The number of free inodes in the file system.
avail_inodes
The number of free inodes available to non-privileged processes.
io_size
A suggested optimal block size for I/O operations -- if you're reading or writing
lots of data, do it in chunks of this size.
block_size
The size in bytes of the minimum unit of allocation on this file system.
total_blocks
The total number of blocks in the file system.
free_blocks
The number of free blocks in the file system.
used_blocks
The number of used blocks in the file system.
avail_blocks
The number of free blocks available to non-privileged processes.
systime
The time in seconds since epoch when the statistic was retrieved from kernel.
BUGS
Only mounted file systems are recognised.
Some file systems might be reported twice when mounted on different mount points.
The compare functions exist rather for backward compatibility than for functionality
enhancements. Limited flexibility (e.g. reverse order) and lack of optimising
opportunities for the compiler leads to the recommendation to implement the required
compare routines locally.
Calling sg_set_valid_filesystems with an empty list with clear the internal list of valid
file systems. There's currently no way to reset to the initial list.
SEE ALSO
statgrab(3)
WEBSITE
⟨https://libstatgrab.org/⟩