Interface(3pm)						User Contributed Perl Documentation					    Interface(3pm)

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
";
	   print "addr =      ",$if->address,"
",
		 "broadcast = ",$if->broadcast,"
",
		 "netmask =   ",$if->netmask,"
",
		 "dstaddr =   ",$if->dstaddr,"
",
		 "hwaddr =    ",$if->hwaddr,"
",
		 "mtu =       ",$if->mtu,"
",
		 "metric =    ",$if->metric,"
",
		 "index =     ",$if->index,"
";

	   print "is running
"     if $if->is_running;
	   print "is broadcast
"   if $if->is_broadcast;
	   print "is p-to-p
"	    if $if->is_pt2pt;
	   print "is loopback
"    if $if->is_loopback;
	   print "is promiscuous
" if $if->is_promiscuous;
	   print "is multicast
"   if $if->is_multicast;
	   print "is notrailers
"  if $if->is_notrailers;
	   print "is noarp
"	    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
";
	   my $flags = $s->if_flags($if);
	   print "addr =      ",$s->if_addr($if),"
",
		 "broadcast = ",$s->if_broadcast($if),"
",
		 "netmask =   ",$s->if_netmask($if),"
",
		 "dstaddr =   ",$s->if_dstaddr($if),"
",
		 "hwaddr =    ",$s->if_hwaddr($if),"
";

	   print "is running
"     if $flags & IFF_RUNNING;
	   print "is broadcast
"   if $flags & IFF_BROADCAST;
	   print "is p-to-p
"	    if $flags & IFF_POINTOPOINT;
	   print "is loopback
"    if $flags & IFF_LOOPBACK;
	   print "is promiscuous
" if $flags & IFF_PROMISC;
	   print "is multicast
"   if $flags & IFF_MULTICAST;
	   print "is notrailers
"  if $flags & IFF_NOTRAILERS;
	   print "is noarp
"	    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!
" if $sock->if_flags & IFF_MULTICAST.

AUTHOR

       Lincoln Stein <lstein@cshl.org>

       This module is distributed under the same license as Perl itself.

SEE ALSO

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

perl v5.14.2							    2011-07-21							    Interface(3pm)