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

FreeBSD Manual Pages

  
 
  

home | help
sg_get_network_io_stats(3)			    sg_get_network_io_stats(3)

NAME
       sg_get_network_io_stats,	    sg_get_network_io_stats_r,	   sg_get_net-
       work_io_stats_diff, sg_get_network_io_stats_diff_between,  sg_free_net-
       work_io_stats, sg_network_io_compare_name - get network statistics

SYNOPSIS
       #include	<statgrab.h>

       sg_network_io_stats *sg_get_network_io_stats (size_t *entries);

       sg_network_io_stats *sg_get_network_io_stats_r (size_t *entries);

       sg_network_io_stats *sg_get_network_io_stats_diff (size_t *entries);

       sg_network_io_stats *sg_get_network_io_stats_diff_between (const
		       sg_network_io_stats *cur, const sg_network_io_stats
		       *last, size_t *entries);

       sg_error	sg_free_network_io_stats (sg_network_iface_stats *data);

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

DESCRIPTION
       The  sg_get_network_io_stats  functions	provide	 network interface I/O
       statistics on a per interface basis. All	get- and  diff-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_network_io_stats() and sg_get_network_io_stats_r() functions
       deliver the I/O-statistics since	the interface has been attached	to the
       system.	   The	  sg_get_network_io_stats_diff()    and	   sg_get_net-
       work_io_stats_diff_between()  deliver  the difference between two calls
       of sg_get_network_io_stats()  or	 sg_get_network_io_stats_r(),  respec-
       tively.

       API Shortcut

       +-----------------------+---------------------+---------------------+
       |function	       | returns	     | data owner	   |
       +-----------------------+---------------------+---------------------+
       |sg_get_net-	       | sg_network_io_stats | libstatgrab (thread |
       |work_io_stats	       | *		     | local)		   |
       +-----------------------+---------------------+---------------------+
       |sg_get_net-	       | sg_network_io_stats | caller		   |
       |work_io_stats_r	       | *		     |			   |
       +-----------------------+---------------------+---------------------+
       |sg_get_net-	       | sg_network_io_stats | libstatgrab (thread |
       |work_io_stats_diff     | *		     | local)		   |
       +-----------------------+---------------------+---------------------+
       |sg_get_net-	       | sg_network_io_stats | caller		   |
       |work_io_stats_diff_be- | *		     |			   |
       |tween		       |		     |			   |
       +-----------------------+---------------------+---------------------+
       sg_network_io_stats vectors received  from  sg_get_network_io_stats_r()
       or   sg_get_network_io_stats_diff_between()   must   be	 freed	 using
       sg_free_network_io_stats() when not needed any more. The	caller is  re-
       sponsible for doing it.

       Additionally  a	support	 function  for qsort(3)	are available: sg_net-
       work_io_compare_name().

       Example

       size_t entries;
       sg_network_io_stats *network_stats = NULL;
       while( NULL != (	network_stats =	sg_get_network_io_stats_diff(&entries) ) ) {
	   /* sort interface by	name */
	   qsort( network_stats, entries, sizeof(network_stats[0]), &sg_network_io_compare_name	);
	   show_network_io_stats( network_stats	);
       }

       sg_get_network_io_stats returns the network traffic stored in the  ker-
       nel  which  holds  the  amount of data transferred since	device was at-
       tached. On some platforms, such as Solaris 7, this value	is stored in a
       32bit  int,  so wraps around when it reaches 4GB. Other platforms, such
       as Solaris 8, hold the value in a 64bit int, which wraps	somewhere near
       17  million terabytes.  The sg_get_network_io_stats_diff() function and
       the sg_get_network_io_stats_diff_between() function  care  about	 these
       overflows and try to detect overflows when the diff is calculated.

RETURN VALUES
       All  network statistics return a	pointer	to a structure of type sg_net-
       work_io_stats.

       typedef struct {
	       char *interface_name;
	       unsigned	long long tx;
	       unsigned	long long rx;
	       unsigned	long long ipackets;
	       unsigned	long long opackets;
	       unsigned	long long ierrors;
	       unsigned	long long oerrors;
	       unsigned	long long collisions;
	       time_t systime;
       } sg_network_io_stats;

       interface_name
	      The name known to	the operating system.  (eg. on linux it	 might
	      be eth0, on AIX en0 and on FreeBSD fxp0)

       tx     The number of bytes transmitted.

       rx     The number of bytes received.

       ipackets
	      The number of packets received.

       opackets
	      The number of packets transmitted.

       ierrors
	      The number of receive errors.

       oerrors
	      The number of transmit errors.

       collisions
	      The number of collisions.

       systime
	      The  timestamp  when  the	above stats where collected in seconds
	      since epoch or the time period over which	tx and rx were	trans-
	      ferred.

BUGS
       sg_get_network_io_stats_diff  and  sg_get_network_io_stats_diff_between
       compare two lists of network interface related I/O statistics. Each en-
       try  occurring only in the second list is passed	through	to the result-
       ing list	as if it would have been compared to an	entry with all statis-
       tic  values  set	to 0. This implies, on the very	first call sg_get_net-
       work_io_stats_diff will return the same as sg_get_network_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_net-
       work_io_stats_diff function will	return 5GB.

SEE ALSO
       statgrab(3)

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

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

home | help