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

FreeBSD Manual Pages

  
 
  

home | help
sg_get_network_iface_stats(3)			 sg_get_network_iface_stats(3)

NAME
       sg_get_network_iface_stats,  sg_get_network_iface_stats_r, sg_free_net-
       work_iface_stats, sg_network_iface_compare_name - get network interface
       statistics

SYNOPSIS
       #include	<statgrab.h>

       sg_network_iface_stats *sg_get_network_iface_stats (size_t *entries);

       sg_network_iface_stats *sg_get_network_iface_stats_r (size_t *entries);

       sg_error	sg_free_network_iface_stats (sg_network_iface_stats *data);

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

DESCRIPTION
       The     functions    sg_get_network_iface_stats()    and	   sg_get_net-
       work_iface_stats_r() return statistics about the	network	interfaces  in
       the  machine. Specifically, they	return the speed of the	interface, the
       duplex state, and whether it is currently up. Both  functions  take  an
       optional	 entries  parameter,  which points (when given)	to a size_t to
       take the	number of returned vector entries.

       API Shortcut

       +-------------------+--------------------+---------------------+
       |function	   | returns		| data owner	      |
       +-------------------+--------------------+---------------------+
       |sg_get_net-	   | sg_net-		| libstatgrab (thread |
       |work_iface_stats   | work_iface_stats *	| local)	      |
       +-------------------+--------------------+---------------------+
       |sg_get_net-	   | sg_net-		| caller	      |
       |work_iface_stats_r | work_iface_stats *	|		      |
       +-------------------+--------------------+---------------------+
       The    sg_network_iface_stats   vectors	 received   from   sg_get_net-
       work_iface_stats_r() must be freed using	 sg_free_network_iface_stats()
       when not	needed any more. The caller is responsible for doing it.

       Additionally  a	support	 function  for	qsort(3) in available: sg_net-
       work_iface_compare_name().

       Sort Example

       size_t entries;
       sg_network_iface_stats *network_iface_stats = NULL;
       while( NULL != (	network_iface_stats = sg_get_network_iface_stats(&entries) ) ) {
	   /* order entries alphabetically using the mountpoint	*/
	   qsort( network_iface_stats, entries,	sizeof(network_iface_stats[0]),	&sg_network_iface_compare_name );
	   show_network_iface_stats( network_iface_stats );
       }

RETURN VALUES
       The sg_get_network_iface_stats returns a	pointer	to a structure of type
       sg_network_iface_stats.

       typedef enum{
	       SG_IFACE_DUPLEX_FULL,
	       SG_IFACE_DUPLEX_HALF,
	       SG_IFACE_DUPLEX_UNKNOWN
       }sg_iface_duplex;

       Note:  The  SG_IFACE_DUPLEX_UNKNOWN value could mean that duplex	hasn't
       been negotiated yet.

       typedef struct {
	       char *interface_name;
	       int speed;
	       sg_iface_duplex duplex;
	       int up;
	       time_t systime;
       } sg_network_iface_stats;

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

       speed  The speed	of the interface, in megabits/sec.

       duplex The  duplex  state  the interface	is in. See sg_iface_duplex for
	      permitted	values.

       up     Whether the interface is up.

       systime
	      The timestamp when the above stats where	collected  in  seconds
	      since epoch

BUGS
       Getting	specific details may require elevated privileges, eg. on Linux
       the interface speed isn't visible to non-privileged processes.

       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.

SEE ALSO
       statgrab(3)

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

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

home | help