Provided by: libnet-interface-perl_1.016-1build3_amd64 bug

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.

       ·   ->interfaces();

           Returns a list of interface objects for each interface that supports IPV4 or IPV6.

           On failure, returns an empty list.

               usage:

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

                   foreach my $if (@all_ifs) {
                     $if_name = $if->name;
                       or
                     print $if, "\n";      # (overloaded)
                   }

               Get or Set (where supported)
                   $old_mtu = $if->mtu($new_mtu);
                   $old_metric = $if->metric($new_metric);
               etc...

       ·   ->new(); has multiple calling invocations.

           This method will refresh the data for an existing interface OR it can modify and
           existing interface OR it can create a new interface or alias.

           ·   $this_if = ->new('eth0');

               Same as ->interfaces above except for a single known interface. An interface
               object is returned for the specific logical device requested.

               On failure return undef

           ·   $refresh_if = ->new();

               The a new (refreshed) interface object is returned for the same logical device.

           ·   $new_if = ->new(%iface_spec);

           ·   $new_if = ->new(\%iface_spec);

               A logical device is created or updated. The specification is contained in a hash
               table that is passed to new either directly or as a reference.

               The interface specification is architecture dependent. For example, adding an
               address to an existing interface.

                       i.e.    Linux

                 $iface_spec = {
                       name      => 'eth0:0',
                       address   => inet_aton('192.168.1.2'),
                       netmask   => inet_aton('255.255.255.0),
                 # netmask may be optionally specified as:
                 #     cidr      => 24,
                       broadcast => inet_aton('192.168.1.255),
                 # optional values, defaults shown
                       metric    => 1,
                       mtu       => 1500,
                 };

               The address family is determined by inspection of the size of the address.

                       i.e.    BSD variants

                 $iface_spec = {
                       name      => 'eth0',    # primary interface
                       alias     => inet_aton('192.168.1.2'),
                       netmask   => inet_aton('255.255.255.255),
                 # netmask may be optionally specified as:
                 #     cidr      => 32,
                 # optional values, defaults shown
                       metric    => 1,
                       mtu       => 1500,
                 };

               The keyword alias says not to change the primary interface but instead to add an
               address to the interface.

       ·   $refresh_if = ->delete($naddr);

           Removes and address from an interface where supported.

       ·   ->name();

           Return the name of the interface.

       ·   ->address([$family],[$index]);

           SCALAR context

           Get the interface specified by the optional $family and $index.

           Absent a $family and $index, the first available interface for the family AF_INET (or
           if not present AF_INET6) will be returned.

           NOTE: this is not a definitive response. The OS may report the interfaces in any
           order. Usually the primary interface is reported first but this is not guaranteed. Use
           ARRAY context instead to get all addresses.

           ARRAY context

           Returns a list of addresses assigned to this interface.

           If a $family is not specified then AF_INET is assumed or AF_INET6 if there are no
           AF_INET addresses present.

       ·   ->netmask([$family],[$index]);

           Similar to ->address([$family],[$index]); above. Netmasks are reported in the same
           order as the addresses above, in matching positions in the returned array.

       ·   ->destination([$family],[$index]);

       ·   ->broadcast([$family],[$index]);

           These to methods are identical in execution. The returned address attribute(s) will be
           destination or broadcast addresses depending on the status of the POINTOPOINT flag.

           Similar to ->address([$family],[$index]); above. If an address attribute is unknown,
           the array slot will contain undef.

       ·   ->hwaddress([$hwaddr]);

           Returns the binary value of the MAC address for the interface. Optionally, where
           supported, it allows setting of the MAC address.

             i.e.  $old_binmac = $if->hwaddress($new_binmac);
                   $new_binmac = $if->hwaddress();

       ·   ->flags([$new_flags]);

           Get or Set (where supported) the flags on the interface.

                   i.e. down an interface.
                   $flags  = $if->flags();
                   $mask   = ~IFF_UP;
                   $old_fg = $if->flags($flags & $mask);
                   $flags  = $if->flags();

                   UPDATES the if object

           NOTE: returns undef if the interface is down or not configured.

       ·   ->mtu([$new_mtu]);

           Get or Set (where supported) the mtu of the interface.

                   $mtu = $if->mtu();
                   $old_mtu = $if->mtu($new_mtu);

                   UPDATES the if object

           NOTE: returns undef if the interface is down or not configured.

       ·   ->metric([$new_metric]);

           Get or Set (where supported) the metric for the interface.

                   $metric = $if->metric();
                   $old_metric = $if->metric($new_metric);

                   UPDATES the if object

           NOTE: returns undef if the interface is down or not configured.

       ·   ->index();

           Get the interface index, not to be confused with the index number of the IP assigned
           to a particular index.

           There is no provision to SET the index.

                   $index = $if->index();

       ·   ->mask2cidr([$naddrmsk]);

       ·   $cidr = mask2cidr($naddrmsk);

           Returns the CIDR (prefix length) for the netmask $naddrmsk.

           When no $naddrmsk is specified the method will return the first address in the first
           family starting with AF_INET, AF_INET6, etc... This is particularly useful for
           interfaces with only a single address assigned.

           May be called as a METHOD or a FUNCTION.

       ·   ->mac_bin2hex();

       ·   $mac_txt = mac_bin2hex($bin_mac);

           Converts a binary MAC address into hex text.

             i.e. A1:B2:C3:D4:E5:F6

           May be called as a METHOD or a FUNCTION.

       ·   ->info();

           Returns a pointer to a hash containing information about the interface as follows:

             $info = {
                   name    => 'eth0',
                   index   => 1,
                   mtu     => 1500,
                   metric  => 1,
                   flags   => 1234,
                   mac     => binary_mac_address,
                   $fam0   => {
                           number  => of_addresses,
                           size    => of_address,
                   },
                   $fam1   => etc....
             };

             where $famX is one of AF_INET, AF_INET6, etc...

       ·   ->type([$naddr6]);

       ·   $type = type($naddr6);

           ipV6 method. Returns attributes of an IPV6 address that may be tested with these bit
           masks:

             IPV6_ADDR_ANY                 unknown
             IPV6_ADDR_UNICAST             unicast
             IPV6_ADDR_MULTICAST           multicast
             IPV6_ADDR_ANYCAST             anycast
             IPV6_ADDR_LOOPBACK            loopback
             IPV6_ADDR_LINKLOCAL           link-local
             IPV6_ADDR_SITELOCAL           site-local
             IPV6_ADDR_COMPATv4            compat-v4
             IPV6_ADDR_SCOPE_MASK          scope-mask
             IPV6_ADDR_MAPPED              mapped
             IPV6_ADDR_RESERVED            reserved
             IPV6_ADDR_ULUA                uniq-lcl-unicast
             IPV6_ADDR_6TO4                6to4
             IPV6_ADDR_6BONE               6bone
             IPV6_ADDR_AGU                 global-unicast
             IPV6_ADDR_UNSPECIFIED         unspecified
             IPV6_ADDR_SOLICITED_NODE      solicited-node
             IPV6_ADDR_ISATAP              ISATAP
             IPV6_ADDR_PRODUCTIVE          productive
             IPV6_ADDR_6TO4_MICROSOFT      6to4-ms
             IPV6_ADDR_TEREDO              teredo
             IPV6_ADDR_ORCHID              orchid
             IPV6_ADDR_NON_ROUTE_DOC       non-routeable-doc

               i.e.  if ($type & $mask) {
                         print $mask,"\n";
                     ...

           ... will print the string shown to the right of the bit mask.

           When no $naddr6 is specified the method will return the first AF_INET6 address found.
           This is particularly useful for interfaces with only a single address assigned.

           May be called as a METHOD or a FUNCTION with an $naddr6 argument.

       ·   ->scope([$naddr6]);

       ·   $scope = scope($naddr6);

           Returns the RFC-2373 scope of an IPV6 address that may be equated to these constants.

             RFC2373_GLOBAL        global-scope    0xE
             RFC2373_ORGLOCAL      org-local       0x8
             RFC2373_SITELOCAL     site-local      0x5
             RFC2373_LINKLOCAL     link-local      0x2
             RFC2373_NODELOCAL     loopback        0x1

           One additional constant is provided as there is an out of band scope value mapped
           returned when determining scope. If you want standard RFC2373 scope only, && the
           return value with 0xF

             LINUX_COMPATv4        lx-compat-v4    0x10

               i.e.  if ($scope = $const) {
                         print $const,"\n";
                     ...

           ... will print the string shown to the right of the constant.

           When no $naddr6 is specified the method will return the first AF_INET6 address found.
           This is particularly useful for interfaces with only a single address assigned.

           May be called as a METHOD or a FUNCTION with an $naddr6 argument.

FUNCTIONS

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

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

           Converts a hostname or dotquad ipV4 address into a packed network address.

       ·   $dotquad = inet_ntoa($naddr);

           Convert a binary IPV4 address into a dotquad text string.

       ·   $ipV6_txt = full_inet_ntop($naddr6);

             Returns an uncompressed text string for a net6 address.

             i.e.   FE80:02A0:0000:0000:0000:0000:0123:4567

       ·   $minimized = ipV6compress($ipV6_txt);

           Compress an ipV6 address to the minimum RFC-1884 format

             i.e.  FE80:02A0:0000:0000:0000:0000:0123:4567
             to    FE80:2A0::123:4567

       ·   $ipV6_txt = inet_ntop($naddr6)

             Returns a minimized RFC-1884 IPV6 address

       ·   $naddr6 = inet_pton($ipV6_txt);

           Takes an IPv6 text address of the form described in rfc1884 and returns a naddr6 128
           bit binary address string in network order.

       ·   $cidr = mask2cidr($naddrmsk);

       ·   ->mask2cidr($naddrmsk);

           Returns the CIDR (prefix length) for the netmask $naddrmsk.

           May be called as a FUNCTION or a METHOD.

       ·   $mac_txt = mac_bin2hex($bin_mac);

       ·   ->mac_bin2hex();

           Converts a binary MAC address into hex text.

             i.e. A1:B2:C3:D4:E5:F6

           May be called as a FUNCTION or a METHOD.

       ·   $type = type($naddr6);

       ·   ->type($naddr6);

           ipV6 method. Returns attributes of an IPV6 address that may be tested with the bit
           masks described in detail in the METHOD section above.

           May be called as a FUNCTION or a METHOD with an $naddr6 argument.

       ·   $scope = scope($naddr6);

       ·   ->scope($naddr6);

           Returns the RFC-2373 scope of an IPV6 address that may be equated module constants
           described in detail in the METHOD section above.

           May be called as a FUNCTION or a METHOD with an $naddr6 argument.

       ·   $symbolptr = net_symbols();

           Returns a hash containing most of the network symbols available for this architecture.

             where $symbolptr = {
                   SYMBOL_TEXT => value,
                   ...
             };

           Most all of these symbols have both a numeric and text value. Perl does the right
           thing and uses the numeric value in all logic and arithmetic operations and provides
           the text value for print requests.

           To print the numeric value:

             print (0 + &SYMBOL),"\n";

             i.e.  print (0 + AF_INET()),"\n";

           results in the digit 2 being printed, whereas:

                   print AF_INET,"\n";

           results in the string "inet" being printed.

             NOTE: that many symbols are OS dependent. Do not use
                   numeric values in your code, instead use the symbol.

             i.e. AF_INET, AF_INET6, AF_LINK, etc...

PREREQUISITES

       To build Net::Interface, it is necessary to have kernel development libriaries installed
       on the build system. Systems such as Ubuntu, FreeBSD, etc... do NOT come with these
       libraries installed.

       Your build system must have a fully populated directory

           /usr/include/sys

       Missing header files in the above directory will produce errors saying that symbols such
       as AF_INET and PF_INET are missing.

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-2016 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