Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
sg_get_fs_stats(3)					    sg_get_fs_stats(3)

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_filesys-
       tems,  sg_set_valid_filesystems,	 sg_fs_compare_device_name, sg_fs_com-
       pare_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 sys-
       tems. 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_be- | sg_fs_stats * | caller	       |
       |tween			 |		 |		       |
       +-------------------------+---------------+---------------------+
       |sg_get_valid_filesystems | char	**	 | libstatgrab	(glob- |
       |			 |		 | al)		       |
       +-------------------------+---------------+---------------------+
       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 oper-
       ating systems additionally provide an API  to  learn  the  file	system
       types known or valid to the running OS instance,	which is used when de-
       tected. Nevertheless there are known problems when collecting file sys-
       tem  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 func-
       tions 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 al-
	      ways 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 rec-
       ommendation to implement	the required compare routines locally.

       Calling	sg_set_valid_filesystems with an empty list with clear the in-
       ternal list of valid file systems. There's currently no way to reset to
       the initial list.

SEE ALSO
       statgrab(3)

WEBSITE
       <http://www.i-scream.org/libstatgrab/>

i-scream			  2013-06-20		    sg_get_fs_stats(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | BUGS | SEE ALSO | WEBSITE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sg_get_fs_stats&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help