'\" t -*- coding: UTF-8 -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH sg_get_fs_stats 3 2019-03-08 libstatgrab ""
.SH 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
.SH SYNOPSIS
'nh
.nf
\*(T<#include <statgrab.h>\*(T>
.fi
.sp 1
.PP
.fi
.ad l
\*(T<sg_fs_stats *\fBsg_get_fs_stats\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_fs_stats *\fBsg_get_fs_stats_r\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_fs_stats *\fBsg_get_fs_stats_diff\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_fs_stats *\fBsg_get_fs_stats_diff_between\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const sg_fs_stats *\fIcur\fR, const sg_fs_stats *\fIlast\fR, size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_error \fBsg_free_fs_stats\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(sg_fs_stats *\fIdata\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<const char **\fBsg_get_valid_filesystems\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(size_t *\fIentries\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<sg_error \fBsg_set_valid_filesystems\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const char *\fIvalid_fs\fR[]);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<int \fBsg_fs_compare_device_name\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const void *\fIva\fR, const void *\fIvb\fR);\*(T>
'in \n(.iu-\nxu
.ad b
.PP
.fi
.ad l
\*(T<int \fBsg_fs_compare_mnt_point\fR\*(T> \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
\*(T<(const void *\fIva\fR, const void *\fIvb\fR);\*(T>
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
The \*(T<\fBsg_get_fs_stats\fR\*(T> functions provide statistics
of mounted file systems. Both functions take an optional
\*(T<entries\*(T> parameter, which points (when given)
to a size_t to take the number of returned vector entries.
.PP
The \*(T<\fBsg_get_fs_stats\fR\*(T>() and
\*(T<\fBsg_get_fs_stats_r\fR\*(T>() functions deliver the
file system statistics of the moment the function is called. The
\*(T<\fBsg_get_fs_stats_diff\fR\*(T>() and
\*(T<\fBsg_get_fs_stats_diff_between\fR\*(T>() deliver
the difference between two calls of
\*(T<\fBsg_get_fs_stats\fR\*(T>() or
\*(T<\fBsg_get_fs_stats_r\fR\*(T>(), respectively.
.PP
\fBAPI Shortcut\fR
.TS
allbox ;
l | l | l.
T{
function
T}	T{
returns
T}	T{
data owner
T}
.T&
l | l | l.
T{
sg_get_fs_stats
T}	T{
\*(T<sg_fs_stats\*(T> *
T}	T{
libstatgrab (thread local)
T}
T{
sg_get_fs_stats_r
T}	T{
\*(T<sg_fs_stats\*(T> *
T}	T{
caller
T}
T{
sg_get_fs_stats_diff
T}	T{
\*(T<sg_fs_stats\*(T> *
T}	T{
libstatgrab (thread local)
T}
T{
sg_get_fs_stats_diff_between
T}	T{
\*(T<sg_fs_stats\*(T> *
T}	T{
caller
T}
T{
sg_get_valid_filesystems
T}	T{
char **
T}	T{
libstatgrab (global)
T}
.TE
.PP
The \*(T<sg_fs_stats\*(T> vectors received from
\*(T<\fBsg_get_fs_stats_r\fR\*(T>() or
\*(T<\fBsg_get_fs_stats_diff_between\fR\*(T>() must be
freed using \*(T<\fBsg_free_fs_stats\fR\*(T>() when not
needed anymore. The caller is responsible for doing it.
.PP
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.
.PP
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
\*(T<\fBsg_get_valid_filesystems\fR\*(T>() and the
\*(T<\fBsg_set_valid_filesystems\fR\*(T>(). The list of
\*(T<char *\*(T> parameters both functions work with is
always finished with an element pointing to NULL.
.PP
The returned list of
\*(T<\fBsg_get_valid_filesystems\fR\*(T>() must not be modified.
Always copy the list into an own structure, if you plan to extend or
reduce the list:

\fBRemove Network FS Example\fR
.PP
.nf
\*(T<
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 );
}
        \*(T>
.fi

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.
.PP
The list returned by \*(T<\fBsg_get_valid_filesystems\fR\*(T>()
might become invalid when used while the process makes calls to
\*(T<\fBsg_set_valid_filesystems\fR\*(T>(). 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.
.PP
Additionally two support functions for \*(T<\fBqsort\fR\*(T>(3)
are available: \*(T<\fBsg_fs_compare_device_name\fR\*(T>() and
\*(T<\fBsg_fs_compare_mnt_point\fR\*(T>().

\fBSort Example\fR
.PP
.nf
\*(T<
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 );
}
        \*(T>
.fi
.SH "RETURN VALUES"
\*(T<\fBsg_get_fs_stats\fR\*(T> returns a pointer to a
structure of type \*(T<sg_fs_stats\*(T>.
.PP
.nf
\*(T<
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;
    \*(T>
.fi
.PP
.nf
\*(T<
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;
    \*(T>
.fi
.TP 
\*(T<device_name\*(T> 
The name known to the operating system.
(eg. on linux it might be hda)
.TP 
\*(T<fs_type\*(T> 
The file system type of the file system (eg. hpfs or ufs).
.TP 
\*(T<mnt_point\*(T> 
The mount point at which the file system is mounted.
.TP 
\*(T<device_type\*(T> 
The device type of the file system, currently not filled and
always sg_fs_unknown.
.TP 
\*(T<size\*(T> 
The total size, in bytes, of the file system.

size = used + free
.TP 
\*(T<used\*(T> 
The amount of space, in bytes, used on the file system.
.TP 
\*(T<avail\*(T> 
The amount of space, in bytes, available on the file system for
non-privileged users/processes (free space less reserved space).

avail = free - reserved
.TP 
\*(T<free\*(T> 
The amount of space, in bytes, free on the file system.
.TP 
\*(T<total_inodes\*(T> 
The total number of inodes in the file system.
.TP 
\*(T<used_inodes\*(T> 
The number of used inodes in the file system.
.TP 
\*(T<free_inodes\*(T> 
The number of free inodes in the file system.
.TP 
\*(T<avail_inodes\*(T> 
The number of free inodes available to non-privileged processes.
.TP 
\*(T<io_size\*(T> 
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.
.TP 
\*(T<block_size\*(T> 
The size in bytes of the minimum unit of allocation on this
file system.
.TP 
\*(T<total_blocks\*(T> 
The total number of blocks in the file system.
.TP 
\*(T<free_blocks\*(T> 
The number of free blocks in the file system.
.TP 
\*(T<used_blocks\*(T> 
The number of used blocks in the file system.
.TP 
\*(T<avail_blocks\*(T> 
The number of free blocks available to non-privileged processes.
.TP 
\*(T<systime\*(T> 
The time in seconds since epoch when the statistic was
retrieved from kernel.
.SH BUGS
Only mounted file systems are recognised.
.PP
Some file systems might be reported twice when mounted on different
mount points.
.PP
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.
.PP
Calling \*(T<\fBsg_set_valid_filesystems\fR\*(T> with an empty
list with clear the internal list of valid file systems. There's
currently no way to reset to the initial list.
.SH "SEE ALSO"
\fBstatgrab\fR(3)
.SH WEBSITE
\(lahttps://libstatgrab.org/\(ra