Michael Robinton > Net-Interface-1.012 > Net::Interface

Download:
Net-Interface-1.012.tar.gz

Dependencies

Annotate this POD

Related Modules

MIME::Lite
Net::Pcap
Sys::Hostname
MIME::Types
LWP::UserAgent
Net::Telnet
IO::Socket
Inline::C
Net::Domain
more...
By perlmonks.org

CPAN RT

New  4
Open  4
View/Report Bugs
Module Version: 1.012   Source  

NAME ^

Net::Interface - Perl extension to access network interfaces

SYNOPSIS ^

  use Net::Interface qw(
        cidr2mask
        full_inet_ntop
        ipV6compress
        mac_bin2hex
        mask2cidr
        net_symbols
        type
        scope
        inet_aton
        inet_ntoa
        inet_pton
        inet_ntop
        :afs
        :pfs
        :ifs
        :iffs
        :iffIN6
        :iftype
        :scope
        :constants
        :inet
        :all
        :lower
        :upper
  );

TAGS

  Note: tags :afs, :pfs, :constants, :ifs
        include all AF_[family names], PF_[family names] and
        IFxxxx values that exist on this architecture.

        :iffs includes only IFF_xxx values
        :iffIN6 includes IN6_IFF_xxx values on BSD flavored OS's

        :inet includes inet_aton, inet_ntoa,
                inet_pton, inet_ntop

  On platforms that support IPV6, :iftype :scope 
  provide additional attribute screening

  :constants is a deprecated synonym for :ifs

See Net::Interface::NetSymbols built specifically for this platform for a detailed list and description of all symbols available on this specific architecture and operating systems version.

By default Net::Interface functions and methods return string IPv6 addresses and MAC addresses in uppercase. To change that to lowercase:

  use Net::Interface qw(:lower);

To ensure the current string case behavior even if the default changes:

  use Net::Interface qw(:upper);

FUNCTIONS and METHODS

  @all_ifs = Net::Interface->interfaces();

  $this_if    = Net::Interface->new('eth0');
  $refresh_if = $any_if->new();
  $refresh_if = $this_if->delete($naddr);

  $create_if  = Net::Interface->new(\%iface_spec);

  @ifnames     = "@all_ifs";
  $if_name_txt = $if->name;

  print $if,"\n";       # prints the name
  print "@all_ifs\n"    # prints all names

 ---------------------------------------------
        WARNING API CHANGE !

    $naddr = $if->address([$family],[$index]);
    $naddr = $if->netmask([$family],[$index]);
    $naddr = $if->destination([$family],[$index]);
        same as
    $naddr = $if->broadcast([$family],[$index]);

    @addresses = $if->address([$family]);
    @netmasks  = $if->netmask([$family]);
    @destinats = $if->destination([$family]);
        same as
    @broaddrs  = $if->broadcast([$family]);

    $bin_mac = $if->hwaddress($hwaddr);
 ---------------------------------------------

  $val = $if->flags($val);
  $val = $if->mtu ($val);
  $val = $if->metric($val);
  $val = $if=>index();

  $cidr = $if->mask2cidr([$naddmsk])
  $cidr = mask2cidr($naddrmsk);
  $naddrmsk = cidr2mask($cidr,[family])

  $mac_txt = if->mac_bin2hex();
  $mac_txt = mac_bin2hex($bin_mac);

  $naddr   = inet_aton($host or $dotquad);
  $dotquad = inet_ntoa($naddr);

  $info = $if->info();

    for ipV6 only
  $type  = $if->type([$naddr6]);
  $type  = type($naddr6);
  $scope = $if->scope([$naddr6]);
  $scope = scope($naddr6);

  $full_ipV6_txt = full_inet_ntop($naddr6);
  $ipV6_txt = inet_ntop($naddr6)
  $naddr6   = inet_pton($ipV6_txt);

DESCRIPTION ^

Net::Interface is a module that allows access to the host network interfaces in a manner similar to ifconfig(8). Version 1.00 is a complete re-write and includes support for IPV6 as well as the traditional IPV4.

Both read and write access to network device attributes including the creation of new logical and physical interfaces is available where supported by the OS and this module.

NOTE: if your OS is not supported, please feel free to contribute new capabilities, patches, etc.... see: Net::Interface::Developer

ANOTHER NOTE: Many of the operations of Net::Interface, particularly those that set interface values require privileged access to OS resources. Wherever possible, Net::Interface will simply fail softly when there are not adequate privileges to perform the requested operation or where the operation is not supported.

OPERATION ^

Net::Interface retrieves information about the network devices on its host in a fashion similar to ifconfig(8) running in a terminal window. With ifconfig(8), the information is returned to the screen and any additional activity on a particular network device goes on without the knowledge of the user. Similarly, Net::Interface only retrieves information about network devices when methods interfaces and new are invoked. Calls to interfaces retrieves information about all network devices known to the host. Calls to new make the same function call to the host library but rather than returning all the interface net device information to the user, it selects out only information for the specified device. The function call to the OS is the same. This information is cached in the object returned to the user interface and it is from this object that data is returned to the user program.

To continually monitor a particular device, it is necessary to issue repeat calls to new.

SYMBOLS ^

Net::Interface provide a large number of network interface symbols with a module generated on its build host. These symbols include all of the available AF_xxxx, PF_xxx, IFF_xxx symbols and many more. For a detailed list of all of these symbols, see Net::Interface::NetSymbols.

HINTS and TIPS for use SYMBOLS

Most of the symbols provided by Net::Interface have dual values.

1) a numeric value when use in arithmetic context and

2) a text value when used in string/text context

Symbols are actually calls to functions. Because of this certain usage rules apply that are not necessarily obvious.

If you make it a practice to build your Perl modules using:

  #!/usr/bin/perl
  use strict;

Then usage of symbols will require that they explicitly be called as functions. i.e.

  $functval = &AF_INET          is OK

  $functval = AF_INET()         is better

The first calling method allows the function to pick up the contents of @_. This works fine as long as @_ is empty. Since symbols do not take arguments, when @_ contains something the symbol call will fail with a message from Perl about inappropriate calling syntax.

If you do not use strict; (not recommended) then bare symbols will work just fine in your Perl scripts. You can also imbed your symbols in blocks where strict; is not enforced.

  {
        no strict;
        $functval = AF_INET
  }

Lastly, to access the numeric value of a symbol unconditionally:

  $numeric = 0 + AF_INET

WARNING - API CHANGES ^

The following changes have been made to the API. This may BREAK existing code. If you have been using a previous version of Net::Interface you should verify that these API changes do not break your code.

NO LONGER SUPPORTED

* $naddr=$if->address($naddr);

* $naddr=$if->netmask($naddr);

* $naddr=$if->destination($naddr);

* $naddr=$if->broadcast($naddr);

* $mac = $if-hwaddress($hwaddr);>

Setting address values was never implemented in previous versions of Net::Interface. With this version (where supported) changing an address will be implemented using a hash argument containing the required and optional elements in a manner similar to ifconfig(8). See:

        Net::Interface->new(\%iface_spec);

NO LONGER SUPPORTED

* ($sa_family,$size,$naddr)=$if->address($naddr);

On most platforms, multiple addresses and multiple address families can be assigned to the same interface. The returned data described above conflicts with the requirement to report multiple addresses for a particular interface. In addition, the returned information only reflected the attributes of the FIRST address assigned to the device where there could be many of mixed families. i.e. AF_INET, AF_INET6, and perhaps more as the capabilities of this module are enhanced to support additional address families.

The API has been changed to reflect this reality and the need to report multiple addresses on the same interface.

        @addresses = $if->address([$family]);

The new API is described in detail later in this document.

NO LONGER SUPPORTED

* ($sa_family,$size,$hwaddr)=$if->hwaddress($hwaddr);

As in the preceding case, it is not possible to accurately report the address family attributes of an interface which may support assignments of more than one address from differing address families.

        see: if->info();

METHODS ^

Brackets [] indicates an optional parameter.

The return value for SET attempts on systems that do not support the operation is not settled. Current practice is to silently ignore the set request. This may change so don't count on this behavior.

Unless otherwise specified, errors for all methods return either undef or and empty array depending on the expected return context.

FUNCTIONS ^

Unless otherwise specified, errors for all methods return either undef or and empty array depending on the expected return context.

ACKNOWLEDGEMENTS ^

This version of Net::Interface has been completely rewritten and updated to include support for IPV6. Credit should be given to the original author

        Stephen Zander <gibreel@pobox.com>

for conceiving the idea behind Net::Interface and to the work done by

        Jerrad Pierce jpierce@cpan.org

on the maintenance and improvements to the original version.

Thanks also go to

        Jens Rehsack <rehsack@web.de>

for inspiring me to create this updated version and for his assistance in vetting the design concepts and loads of other helpful things.

The following functions are used in whole or in part as include files to Interface.xs. The copyright (same as Perl itself) is include in the file.

    file:              functions:

  miniSocketXS.c  inet_aton, inet_ntoa

inet_aton, inet_ntoa are from the perl-5.8.0 release by Larry Wall, copyright 1989-2002. inet_aton, inet_ntoa code is current through perl-5.9.3 release. Thank you Larry for making PERL possible for all of us.

COPYRIGHT 2008-2009 Michael Robinton <michael@bizsystems.com> ^

All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of either:

  a) the GNU General Public License as published by the Free
  Software Foundation; either version 2, or (at your option) any
  later version, or

  b) the "Artistic License" which comes with this distribution.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.

You should have received a copy of the Artistic License with this distribution, in the file named "Artistic". If not, I'll be glad to provide one.

You should also have received a copy of the GNU General Public License along with this program in the file named "Copying". If not, write to the

        Free Software Foundation, Inc.
        59 Temple Place, Suite 330
        Boston, MA  02111-1307, USA

or visit their web page on the internet at:

        http://www.gnu.org/copyleft/gpl.html.

SEE ALSO ^

ifconfig(8), Net::Interface::NetSymbols, Net::Interface::Developer

syntax highlighting: