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

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