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

FreeBSD Manual Pages

  
 
  

home | help
sg_get_disk_io_stats(3)				       sg_get_disk_io_stats(3)

NAME
       sg_get_disk_io_stats,			       sg_get_disk_io_stats_r,
       sg_get_disk_io_stats_diff,	    sg_get_disk_io_stats_diff_between,
       sg_free_disk_io_stats,	  sg_disk_io_compare_name,     sg_disk_io_com-
       pare_traffic - get disk io statistics

SYNOPSIS
       #include	<statgrab.h>

       sg_disk_io_stats	*sg_get_disk_io_stats (size_t *entries);

       sg_disk_io_stats	*sg_get_disk_io_stats_r	(size_t	*entries);

       sg_disk_io_stats	*sg_get_disk_io_stats_diff (size_t *entries);

       sg_disk_io_stats	*sg_get_disk_io_stats_diff_between (const
		       sg_disk_io_stats	*cur, const sg_disk_io_stats *last,
		       size_t *entries);

       sg_error	sg_free_disk_io_stats (sg_disk_io_stats	*data);

       int sg_disk_io_compare_name (const void *va, const void *vb);

       int sg_disk_io_compare_traffic (const void *va, const void *vb);

DESCRIPTION
       The sg_get_disk_io_stats	functions provide disk I/O statistics on a per
       disk basis. All get- and	diff-functions take an optional	entries	param-
       eter, which points (when	given) to a size_t to take the number  of  re-
       turned vector entries.

       The  sg_get_disk_io_stats()  and	sg_get_disk_io_stats_r() functions de-
       liver the I/O-statistics	since the disk has been	attached to  the  sys-
       tem.  The sg_get_disk_io_stats_diff() and sg_get_disk_io_stats_diff_be-
       tween()	 deliver    the	   difference	 between    two	   calls    of
       sg_get_disk_io_stats() or sg_get_disk_io_stats_r(), respectively.

       API Shortcut

       +------------------------------+--------------------+---------------------+
       |function		      |	returns		   | data owner		 |
       +------------------------------+--------------------+---------------------+
       |sg_get_disk_io_stats	      |	sg_disk_io_stats * | libstatgrab (thread |
       |			      |			   | local)		 |
       +------------------------------+--------------------+---------------------+
       |sg_get_disk_io_stats_r	      |	sg_disk_io_stats * | caller		 |
       +------------------------------+--------------------+---------------------+
       |sg_get_disk_io_stats_diff     |	sg_disk_io_stats * | libstatgrab (thread |
       |			      |			   | local)		 |
       +------------------------------+--------------------+---------------------+
       |sg_get_disk_io_stats_diff_be- |	sg_disk_io_stats * | caller		 |
       |tween			      |			   |			 |
       +------------------------------+--------------------+---------------------+
       sg_disk_io_stats	  vectors   got	  from	 sg_get_disk_io_stats_r()   or
       sg_get_disk_io_stats_diff_between()     must	be     freed	 using
       sg_free_disk_io_stats() when not	needed any more. The caller is respon-
       sible for doing it.

       Additionally  two  support  functions  for  qsort(3)   are   available:
       sg_disk_io_compare_name() and sg_disk_io_compare_traffic().

       Example

       size_t entries;
       sg_disk_io_stats	*io_stats = NULL;
       while( NULL != (	io_stats = sg_get_disk_io_stats_diff(&entries) ) ) {
	   /* show disks with most traffic first */
	   qsort( io_stats, entries, sizeof(io_stats[0]), &sg_disk_io_compare_traffic );
	   show_disk_io_stats( io_stats	);
       }

       On  some	 platforms, such as Solaris 7, the kernel value	is stored in a
       32bit int, so wraps around when it reaches 4GB. Other  platforms,  such
       as Solaris 8 (and most other modern systems), hold the value in a 64bit
       int,  which  wraps  somewhere   near   17   million   terabytes.	   The
       sg_get_disk_io_stats_diff()	    function	      and	   the
       sg_get_disk_io_stats_diff_between() function care about these overflows
       and try to detect overflows when	the diff is calculated.

       On  Solaris libstatgrab will attempt to get the cXtXdXsX	representation
       for the disk_name string. If it fails it	will use a name	like  sd0.  On
       some systems programs calling libstatgrab will need elevated privileges
       to lookup some of the names. The	mappings are built up  when  sg_init()
       is called for the first time.

RETURN VALUES
       All  diskio  statistics	return	a  pointer  to	a  structure  of  type
       sg_disk_io_stats.

       typedef struct {
	       char *disk_name;
	       unsigned	long long read_bytes;
	       unsigned	long long write_bytes;
	       time_t systime;
       } sg_disk_io_stats;

       disk_name
	      The name known to	the operating system.  (eg. on linux it	 might
	      be hda)

       read_bytes
	      The number of bytes the disk has read.

       write_bytes
	      The number of bytes the disk has written.

       systime
	      The  time	 period	 over  which  read_bytes  and write_bytes were
	      transferred.

BUGS
       sg_get_disk_io_stats_diff and sg_get_disk_io_stats_diff_between compare
       two lists of disk (block	device)	related	I/O statistics.	Each entry oc-
       curring only in the second list is passed through to the	resulting list
       as if it	would have been	compared to an entry with all statistic	values
       set   to	  0.	This	implies,    on	  the	 very	 first	  call
       sg_get_disk_io_stats_diff will return the same as sg_get_disk_io_stats.

       On  operating  systems that hold	only 32bits of data there is a problem
       if the values wrap twice. For example, on Solaris 7 if  9GB  is	trans-
       ferred	 and	the    operating    system    wraps    at   4GB,   the
       sg_get_disk_io_stats_diff() function will return	5GB.

       The compare functions exists 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.

SEE ALSO
       statgrab(3)

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

i-scream			  2013-06-07	       sg_get_disk_io_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_disk_io_stats&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help