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

FreeBSD Manual Pages

  
 
  

home | help
IO::Interface(3)      User Contributed Perl Documentation     IO::Interface(3)

NAME
       IO::Interface - Perl extension for access to network card configuration
       information

SYNOPSIS
	# ======================
	# the new, preferred API
	# ======================

	use IO::Interface::Simple;

	my $if1	  = IO::Interface::Simple->new('eth0');
	my $if2	  = IO::Interface::Simple->new_from_address('127.0.0.1');
	my $if3	  = IO::Interface::Simple->new_from_index(1);

	my @interfaces = IO::Interface::Simple->interfaces;

	for my $if (@interfaces) {
	   print "interface = $if\n";
	   print "addr =      ",$if->address,"\n",
		 "broadcast = ",$if->broadcast,"\n",
		 "netmask =   ",$if->netmask,"\n",
		 "dstaddr =   ",$if->dstaddr,"\n",
		 "hwaddr =    ",$if->hwaddr,"\n",
		 "mtu =	      ",$if->mtu,"\n",
		 "metric =    ",$if->metric,"\n",
		 "index	=     ",$if->index,"\n";

	   print "is running\n"	    if $if->is_running;
	   print "is broadcast\n"   if $if->is_broadcast;
	   print "is p-to-p\n"	    if $if->is_pt2pt;
	   print "is loopback\n"    if $if->is_loopback;
	   print "is promiscuous\n" if $if->is_promiscuous;
	   print "is multicast\n"   if $if->is_multicast;
	   print "is notrailers\n"  if $if->is_notrailers;
	   print "is noarp\n"	    if $if->is_noarp;
	 }

	 # ===========
	 # the old API
	 # ===========

	 use IO::Socket;
	 use IO::Interface qw(:flags);

	 my $s = IO::Socket::INET->new(Proto =>	'udp');
	 my @interfaces	= $s->if_list;

	 for my	$if (@interfaces) {
	   print "interface = $if\n";
	   my $flags = $s->if_flags($if);
	   print "addr =      ",$s->if_addr($if),"\n",
		 "broadcast = ",$s->if_broadcast($if),"\n",
		 "netmask =   ",$s->if_netmask($if),"\n",
		 "dstaddr =   ",$s->if_dstaddr($if),"\n",
		 "hwaddr =    ",$s->if_hwaddr($if),"\n";

	   print "is running\n"	    if $flags &	IFF_RUNNING;
	   print "is broadcast\n"   if $flags &	IFF_BROADCAST;
	   print "is p-to-p\n"	    if $flags &	IFF_POINTOPOINT;
	   print "is loopback\n"    if $flags &	IFF_LOOPBACK;
	   print "is promiscuous\n" if $flags &	IFF_PROMISC;
	   print "is multicast\n"   if $flags &	IFF_MULTICAST;
	   print "is notrailers\n"  if $flags &	IFF_NOTRAILERS;
	   print "is noarp\n"	    if $flags &	IFF_NOARP;
	 }

	 my $interface = $s->addr_to_interface('127.0.0.1');

DESCRIPTION
       IO::Interface adds methods to IO::Socket	objects	that allows them to be
       used to retrieve	and change information about the network interfaces on
       your system.  In	addition to the	object-oriented	access methods,	you
       can use a function-oriented style.

       THIS API	IS DEPRECATED. Please see IO::Interface::Simple	for the
       preferred way to	get and	set interface configuration information.

   Creating a Socket to	Access Interface Information
       You must	create a socket	before you can access interface	information.
       The socket does not have	to be connected	to a remote site, or even used
       for communication.  The simplest	procedure is to	create a UDP protocol
       socket:

	 my $s = IO::Socket::INET->new(Proto =>	'udp');

       The various IO::Interface functions will	now be available as methods on
       this socket.

   Methods
       @iflist = $s->if_list
	   The if_list() method	will return a list of active interface names,
	   for example "eth0" or "tu0".	 If no interfaces are configured and
	   running, returns an empty list.

       $addr = $s->if_addr($ifname [,$newaddr])
	   if_addr() gets or sets the interface	address.  Call with the
	   interface name to retrieve the address (in dotted decimal format).
	   Call	with a new address to set the interface.  In the latter	case,
	   the routine will return a true value	if the operation was
	   successful.

	     my	$oldaddr = $s->if_addr('eth0');
	     $s->if_addr('eth0','192.168.8.10')	|| die "couldn't set address: $!";

	   Special case: the address of	the pseudo-device "any"	will return
	   the IP address "0.0.0.0", which corresponds to the INADDR_ANY
	   constant.

       $broadcast = $s->if_broadcast($ifname [,$newbroadcast]
	   Get or set the interface broadcast address.	If the interface does
	   not have a broadcast	address, returns undef.

       $mask = $s->if_netmask($ifname [,$newmask])
	   Get or set the interface netmask.

       $dstaddr	= $s->if_dstaddr($ifname [,$newdest])
	   Get or set the destination address for point-to-point interfaces.

       $hwaddr = $s->if_hwaddr($ifname [,$newhwaddr])
	   Get or set the hardware address for the interface. Currently	only
	   ethernet addresses in the form "00:60:2D:2D:51:70" are accepted.

       $flags =	$s->if_flags($ifname [,$newflags])
	   Get or set the flags	for the	interface.  The	flags are a bitmask
	   formed from a series	of constants.  See "Exportable constants"
	   below.

       $ifname = $s->addr_to_interface($ifaddr)
	   Given an interface address in dotted	form, returns the name of the
	   interface associated	with it.  Special case:	the INADDR_ANY
	   address, 0.0.0.0 will return	a pseudo-interface name	of "any".

   EXPORT
       IO::Interface exports nothing by	default.  However, you can import the
       following symbol	groups into your namespace:

	 :functions   Function-oriented	interface (see below)
	 :flags	      Flag constants (see below)
	 :all	      All of the above

   Function-Oriented Interface
       By importing the	":functions" set, you can access IO::Interface in a
       function-oriented manner.  This imports all the methods described above
       into your namespace.  Example:

	 use IO::Socket;
	 use IO::Interface ':functions';

	 my $sock = IO::Socket::INET->new(Proto=>'udp');
	 my @interfaces	= if_list($sock);
	 print "address	= ",if_addr($sock,$interfaces[0]);

   Exportable constants
       The ":flags" constant imports the following constants for use with the
       flags returned by if_flags():

	 IFF_ALLMULTI
	 IFF_AUTOMEDIA
	 IFF_BROADCAST
	 IFF_DEBUG
	 IFF_LOOPBACK
	 IFF_MASTER
	 IFF_MULTICAST
	 IFF_NOARP
	 IFF_NOTRAILERS
	 IFF_POINTOPOINT
	 IFF_PORTSEL
	 IFF_PROMISC
	 IFF_RUNNING
	 IFF_SLAVE
	 IFF_UP

       This example determines whether interface 'tu0' supports	multicasting:

	 use IO::Socket;
	 use IO::Interface ':flags';
	 my $sock = IO::Socket::INET->new(Proto=>'udp');
	 print "can multicast!\n" if $sock->if_flags & IFF_MULTICAST.

AUTHOR
       Lincoln D. Stein	<lincoln.stein@gmail.com> Copyright 2001-2014, Lincoln
       D. Stein.

       This library is distributed under the Perl Artistic License 2.0.	Please
       see LICENSE for more information.

SUPPORT
       For feature requests, bug reports and code contributions, please	use
       the GitHub repository at	https://github.com/lstein/LibIO-Interface-Perl

SEE ALSO
       perl(1),	IO::Socket(3), IO::Multicast(3), IO::Interface::Simple

perl v5.32.0			  2020-08-08		      IO::Interface(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | SUPPORT | SEE ALSO

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

home | help