Provided by: libstatgrab-dev_0.92.1-1.2build1_amd64 bug

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/⟩