.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Interface 3pm"
.TH Interface 3pm "2020-11-09" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Interface \- Perl extension to access network interfaces
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&  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
\&  );
.Ve
.SS "\s-1TAGS\s0"
.IX Subsection "TAGS"
.Vb 3
\&  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\*(Aqs
\&
\&        :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
.Ve
.PP
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.
.PP
By default \fBNet::Interface\fR functions and methods return string IPv6
addresses and \s-1MAC\s0 addresses in uppercase.  To change that to lowercase:
.PP
.Vb 1
\&  use Net::Interface qw(:lower);
.Ve
.PP
To ensure the current string case behavior even if the default
changes:
.PP
.Vb 1
\&  use Net::Interface qw(:upper);
.Ve
.SS "\s-1FUNCTIONS\s0 and \s-1METHODS\s0"
.IX Subsection "FUNCTIONS and METHODS"
.Vb 1
\&  @all_ifs = Net::Interface\->interfaces();
\&
\&  $this_if    = Net::Interface\->new(\*(Aqeth0\*(Aq);
\&  $refresh_if = $any_if\->new();
\&  $refresh_if = $this_if\->delete($naddr);
\&
\&  $create_if  = Net::Interface\->new(\e%iface_spec);
\&
\&  @ifnames     = "@all_ifs";
\&  $if_name_txt = $if\->name;
\&
\&  print $if,"\en";       # prints the name
\&  print "@all_ifs\en"    # 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBNet::Interface\fR is a module that allows access to the host network
interfaces in a manner similar to \fI\f(BIifconfig\fI\|(8)\fR. Version 1.00 is a complete
re-write and includes support for \s-1IPV6\s0 as well as the traditional \s-1IPV4.\s0
.PP
Both read and write access to network device attributes including the
creation of new logical and physical interfaces is available where
supported by the \s-1OS\s0 and this module.
.PP
\&\s-1NOTE:\s0 if your \s-1OS\s0 is not supported, please feel free to contribute new
capabilities, patches, etc.... see: Net::Interface::Developer
.PP
\&\s-1ANOTHER NOTE:\s0 Many of the operations of \fBNet::Interface\fR, particularly
those that set interface values require privileged access to \s-1OS\s0 resources.
Wherever possible, \fBNet::Interface\fR will simply fail \fIsoftly\fR when there
are not adequate privileges to perform the requested operation or where the
operation is not supported.
.SH "OPERATION"
.IX Header "OPERATION"
\&\fBNet::Interface\fR retrieves information about the network devices on its
host in a fashion similar to \fI\f(BIifconfig\fI\|(8)\fR running in a terminal window.
With \fI\f(BIifconfig\fI\|(8)\fR, 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, \fBNet::Interface\fR only retrieves
information about network devices when methods \fIinterfaces\fR and \fInew\fR are
invoked. Calls to \fIinterfaces\fR retrieves information about all network
devices known to the host. Calls to \fInew\fR 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 \s-1OS\s0 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.
.PP
To continually monitor a particular device, it is necessary to issue
repeat calls to \fInew\fR.
.SH "SYMBOLS"
.IX Header "SYMBOLS"
\&\fBNet::Interface\fR 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.
.SS "\s-1HINTS\s0 and \s-1TIPS\s0 for use \s-1SYMBOLS\s0"
.IX Subsection "HINTS and TIPS for use SYMBOLS"
Most of the symbols provided by \fBNet::Interface\fR have dual values.
.PP
1) a numeric value when use in arithmetic context and
.PP
2) a text value when used in string/text context
.PP
Symbols are actually calls to functions. Because of this certain usage rules
apply that are not necessarily obvious.
.PP
If you make it a practice to build your Perl modules using:
.PP
.Vb 2
\&  #!/usr/bin/perl
\&  use strict;
.Ve
.PP
Then usage of symbols will require that they explicitly be called as
functions. i.e.
.PP
.Vb 1
\&  $functval = &AF_INET          is OK
\&
\&  $functval = AF_INET()         is better
.Ve
.PP
The first calling method allows the function to pick up the contents of
\&\fB\f(CB@_\fB\fR. This works fine as long as \fB\f(CB@_\fB\fR is empty. Since symbols do not take
arguments, when \fB\f(CB@_\fB\fR contains something the symbol call will fail with a
message from Perl about inappropriate calling syntax.
.PP
If you do not \f(CW\*(C`use strict;\*(C'\fR (not recommended) then bare symbols will work just fine in your
Perl scripts. You can also imbed your symbols in blocks where \fBstrict;\fR is
not enforced.
.PP
.Vb 4
\&  {
\&        no strict;
\&        $functval = AF_INET
\&  }
.Ve
.PP
Lastly, to access the numeric value of a symbol unconditionally:
.PP
.Vb 1
\&  $numeric = 0 + AF_INET
.Ve
.SH "WARNING \- API CHANGES"
.IX Header "WARNING - API CHANGES"
The following changes have been made to the \s-1API.\s0 This may \fI\s-1BREAK\s0\fR existing
code. If you have been using a previous version of Net::Interface you should
verify that these \s-1API\s0 changes do not break your code.
.PP
\&\fB\s-1NO LONGER SUPPORTED\s0\fR
.IP "\(bu" 6
\&\fI\f(CI$naddr\fI=$if\->address($naddr);\fR
.IP "\(bu" 6
\&\fI\f(CI$naddr\fI=$if\->netmask($naddr);\fR
.IP "\(bu" 6
\&\fI\f(CI$naddr\fI=$if\->destination($naddr);\fR
.IP "\(bu" 6
\&\fI\f(CI$naddr\fI=$if\->broadcast($naddr);\fR
.IP "\(bu" 6
\&\fI\f(CI$mac\fI = \f(CI$if\fI\-\fRhwaddress($hwaddr);>
.PP
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 \fI\f(BIifconfig\fI\|(8)\fR. See:
.PP
.Vb 1
\&        Net::Interface\->new(\e%iface_spec);
.Ve
.PP
\&\fB\s-1NO LONGER SUPPORTED\s0\fR
.IP "\(bu" 6
\&\fI($sa_family,$size,$naddr)=$if\->address($naddr);\fR
.PP
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 \fI\s-1FIRST\s0\fR address assigned to the device where there could
be many of mixed families. i.e. \s-1AF_INET, AF_INET6,\s0 and perhaps more as the
capabilities of this module are enhanced to support additional address
families.
.PP
The \s-1API\s0 has been changed to reflect this reality and the need to report
multiple addresses on the same interface.
.PP
.Vb 1
\&        @addresses = $if\->address([$family]);
.Ve
.PP
The new \s-1API\s0 is described in detail later in this document.
.PP
\&\fB\s-1NO LONGER SUPPORTED\s0\fR
.IP "\(bu" 6
\&\fI($sa_family,$size,$hwaddr)=$if\->hwaddress($hwaddr);\fR
.PP
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.
.PP
.Vb 1
\&        see: if\->info();
.Ve
.SH "METHODS"
.IX Header "METHODS"
Brackets [] indicates an optional parameter.
.PP
The return value for \fI\s-1SET\s0\fR 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.
.PP
Unless otherwise specified, errors for all methods return either \fBundef\fR or and empty array depending
on the expected return context.
.IP "\(bu" 4
\&\fI\->\f(BIinterfaces()\fI;\fR
.Sp
Returns a list of interface objects for each interface that supports \s-1IPV4\s0
or \s-1IPV6.\s0
.Sp
On failure, returns an empty list.
.Sp
.Vb 1
\&    usage:
\&
\&        @all_ifs = Net::Interface\->interfaces();
\&
\&        foreach my $if (@all_ifs) {
\&          $if_name = $if\->name;
\&            or
\&          print $if, "\en";      # (overloaded)
\&        }
\&
\&    Get or Set (where supported)
\&        $old_mtu = $if\->mtu($new_mtu);
\&        $old_metric = $if\->metric($new_metric);
\&    etc...
.Ve
.IP "\(bu" 4
\&\fI\->\f(BInew()\fI;\fR has multiple calling invocations.
.Sp
This method will refresh the data for an existing interface \s-1OR\s0 it can modify
and existing interface \s-1OR\s0 it can create a new interface or alias.
.RS 4
.IP "\(bu" 4
\&\f(CW$this_if\fR = \fI\->new('eth0');\fR
.Sp
Same as \fI\->interfaces\fR above except for a single known interface. An
interface object is returned for the specific logical device requested.
.Sp
On failure return \fBundef\fR
.IP "\(bu" 4
\&\f(CW$refresh_if\fR = \fI\->\f(BInew()\fI;\fR
.Sp
The a new (refreshed) interface object is returned for the same logical
device.
.IP "\(bu" 4
\&\f(CW$new_if\fR = \fI\->new(%iface_spec);\fR
.IP "\(bu" 4
\&\f(CW$new_if\fR = \fI\->new(\e%iface_spec);\fR
.Sp
A logical device is created or updated. The specification is contained in a hash
table that is passed to \fInew\fR either directly or as a reference.
.Sp
The interface specification is architecture dependent. For example, adding
an address to an existing interface.
.Sp
.Vb 1
\&        i.e.    Linux
\&
\&  $iface_spec = {
\&        name      => \*(Aqeth0:0\*(Aq,
\&        address   => inet_aton(\*(Aq192.168.1.2\*(Aq),
\&        netmask   => inet_aton(\*(Aq255.255.255.0),
\&  # netmask may be optionally specified as:
\&  #     cidr      => 24,
\&        broadcast => inet_aton(\*(Aq192.168.1.255),
\&  # optional values, defaults shown
\&        metric    => 1,
\&        mtu       => 1500,
\&  };
.Ve
.Sp
The address family is determined by inspection of the size of the address.
.Sp
.Vb 1
\&        i.e.    BSD variants
\&
\&  $iface_spec = {
\&        name      => \*(Aqeth0\*(Aq,    # primary interface
\&        alias     => inet_aton(\*(Aq192.168.1.2\*(Aq),
\&        netmask   => inet_aton(\*(Aq255.255.255.255),
\&  # netmask may be optionally specified as:
\&  #     cidr      => 32,
\&  # optional values, defaults shown
\&        metric    => 1,
\&        mtu       => 1500,
\&  };
.Ve
.Sp
The keyword \fBalias\fR says not to change the primary interface but instead to
add an address to the interface.
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\f(CW$refresh_if\fR = \fI\->delete($naddr);\fR
.Sp
Removes and address from an interface where supported.
.IP "\(bu" 4
\&\fI\->\f(BIname()\fI;\fR
.Sp
Return the \fBname\fR of the interface.
.IP "\(bu" 4
\&\fI\->address([$family],[$index]);\fR
.Sp
\&\fB\s-1SCALAR\s0 context\fR
.Sp
Get the interface specified by the optional \f(CW$family\fR and \f(CW$index\fR.
.Sp
Absent a \f(CW$family\fR and \f(CW$index\fR, the first available interface for the
family \s-1AF_INET\s0 (or if not present \s-1AF_INET6\s0) will be returned.
.Sp
\&\s-1NOTE:\s0 this is not a definitive response. The \s-1OS\s0 may report the interfaces in
any order. Usually the primary interface is reported first but this is not
guaranteed. Use \s-1ARRAY\s0 context instead to get all addresses.
.Sp
\&\fB\s-1ARRAY\s0 context\fR
.Sp
Returns a list of addresses assigned to this interface.
.Sp
If a \f(CW$family\fR is not specified then \s-1AF_INET\s0 is assumed or \s-1AF_INET6\s0 if
there are no \s-1AF_INET\s0 addresses present.
.IP "\(bu" 4
\&\fI\->netmask([$family],[$index]);\fR
.Sp
Similar to \fI\->address([$family],[$index]);\fR above. Netmasks are reported in the
same order as the addresses above, in matching positions in the returned
array.
.IP "\(bu" 4
\&\fI\->destination([$family],[$index]);\fR
.IP "\(bu" 4
\&\fI\->broadcast([$family],[$index]);\fR
.Sp
These to methods are identical in execution. The returned address
attribute(s) will be destination or broadcast addresses depending on the
status of the \s-1POINTOPOINT\s0 flag.
.Sp
Similar to \fI\->address([$family],[$index]);\fR above. If an address attribute is
unknown, the array slot will contain \fIundef\fR.
.IP "\(bu" 4
\&\fI\->hwaddress([$hwaddr]);\fR
.Sp
Returns the binary value of the \s-1MAC\s0 address for the interface. Optionally, where
supported, it allows setting of the \s-1MAC\s0 address.
.Sp
.Vb 2
\&  i.e.  $old_binmac = $if\->hwaddress($new_binmac);
\&        $new_binmac = $if\->hwaddress();
.Ve
.IP "\(bu" 4
\&\fI\->flags([$new_flags]);\fR
.Sp
Get or Set (where supported) the flags on the interface.
.Sp
.Vb 5
\&        i.e. down an interface.
\&        $flags  = $if\->flags();
\&        $mask   = ~IFF_UP;
\&        $old_fg = $if\->flags($flags & $mask);
\&        $flags  = $if\->flags();
\&
\&        UPDATES the if object
.Ve
.Sp
\&\s-1NOTE:\s0 returns undef if the interface is down or not configured.
.IP "\(bu" 4
\&\fI\->mtu([$new_mtu]);\fR
.Sp
Get or Set (where supported) the mtu of the interface.
.Sp
.Vb 2
\&        $mtu = $if\->mtu();
\&        $old_mtu = $if\->mtu($new_mtu);
\&
\&        UPDATES the if object
.Ve
.Sp
\&\s-1NOTE:\s0 returns undef if the interface is down or not configured.
.IP "\(bu" 4
\&\fI\->metric([$new_metric]);\fR
.Sp
Get or Set (where supported) the metric for the interface.
.Sp
.Vb 2
\&        $metric = $if\->metric();
\&        $old_metric = $if\->metric($new_metric);
\&
\&        UPDATES the if object
.Ve
.Sp
\&\s-1NOTE:\s0 returns undef if the interface is down or not configured.
.IP "\(bu" 4
\&\fI\->\f(BIindex()\fI;\fR
.Sp
Get the interface index, not to be confused with the index number of the \s-1IP\s0
assigned to a particular index.
.Sp
There is no provision to \s-1SET\s0 the index.
.Sp
.Vb 1
\&        $index = $if\->index();
.Ve
.IP "\(bu" 4
\&\fI\->mask2cidr([$naddrmsk]);\fR
.IP "\(bu" 4
\&\f(CW$cidr\fR = mask2cidr($naddrmsk);
.Sp
Returns the \s-1CIDR\s0 (prefix length) for the netmask \f(CW$naddrmsk\fR.
.Sp
When no \fI\f(CI$naddrmsk\fI\fR is specified the method will return the first address
in the first family starting with \s-1AF_INET, AF_INET6,\s0 etc... This is
particularly useful for interfaces with only a single address assigned.
.Sp
May be called as a \s-1METHOD\s0 or a \s-1FUNCTION.\s0
.IP "\(bu" 4
\&\fI\->\f(BImac_bin2hex()\fI;\fR
.IP "\(bu" 4
\&\f(CW$mac_txt\fR = mac_bin2hex($bin_mac);
.Sp
Converts a binary \s-1MAC\s0 address into hex text.
.Sp
.Vb 1
\&  i.e. A1:B2:C3:D4:E5:F6
.Ve
.Sp
May be called as a \s-1METHOD\s0 or a \s-1FUNCTION.\s0
.IP "\(bu" 4
\&\fI\->\f(BIinfo()\fI;\fR
.Sp
Returns a pointer to a hash containing information about the interface as
follows:
.Sp
.Vb 10
\&  $info = {
\&        name    => \*(Aqeth0\*(Aq,
\&        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...
.Ve
.IP "\(bu" 4
\&\fI\->type([$naddr6]);\fR
.IP "\(bu" 4
\&\f(CW$type\fR = type($naddr6);
.Sp
\&\fBipV6\fR method. Returns attributes of an \s-1IPV6\s0 address that may be tested
with these bit masks:
.Sp
.Vb 10
\&  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,"\en";
\&          ...
.Ve
.Sp
\&... will print the string shown to the right of the bit mask.
.Sp
When no \fI\f(CI$naddr6\fI\fR is specified the method will return the first \s-1AF_INET6\s0
address found. This is particularly useful for interfaces with only a single
address assigned.
.Sp
May be called as a \s-1METHOD\s0 or a \s-1FUNCTION\s0 with an \f(CW$naddr6\fR argument.
.IP "\(bu" 4
\&\fI\->scope([$naddr6]);\fR
.IP "\(bu" 4
\&\f(CW$scope\fR = scope($naddr6);
.Sp
Returns the \s-1RFC\-2373\s0 scope of an \s-1IPV6\s0 address that may be equated to these
constants.
.Sp
.Vb 5
\&  RFC2373_GLOBAL        global\-scope    0xE
\&  RFC2373_ORGLOCAL      org\-local       0x8
\&  RFC2373_SITELOCAL     site\-local      0x5
\&  RFC2373_LINKLOCAL     link\-local      0x2
\&  RFC2373_NODELOCAL     loopback        0x1
.Ve
.Sp
One additional constant is provided as there is an out of band
scope value mapped returned when determining scope. If you want \fBstandard\fR
\&\s-1RFC2373\s0 scope only, && the return value with 0xF
.Sp
.Vb 1
\&  LINUX_COMPATv4        lx\-compat\-v4    0x10
\&
\&    i.e.  if ($scope = $const) {
\&              print $const,"\en";
\&          ...
.Ve
.Sp
\&... will print the string shown to the right of the constant.
.Sp
When no \fI\f(CI$naddr6\fI\fR is specified the method will return the first \s-1AF_INET6\s0
address found. This is particularly useful for interfaces with only a single
address assigned.
.Sp
May be called as a \s-1METHOD\s0 or a \s-1FUNCTION\s0 with an \f(CW$naddr6\fR argument.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
Unless otherwise specified, errors for all methods return either \fBundef\fR or
and empty array depending on the expected return context.
.IP "\(bu" 4
\&\f(CW$naddr\fR = inet_aton($host or \f(CW$dotquad\fR);
.Sp
Converts a hostname or dotquad ipV4 address into a packed network address.
.IP "\(bu" 4
\&\f(CW$dotquad\fR = inet_ntoa($naddr);
.Sp
Convert a binary \s-1IPV4\s0 address into a dotquad text string.
.IP "\(bu" 4
\&\f(CW$ipV6_txt\fR = full_inet_ntop($naddr6);
.Sp
.Vb 1
\&  Returns an uncompressed text string for a net6 address.
\&
\&  i.e.   FE80:02A0:0000:0000:0000:0000:0123:4567
.Ve
.IP "\(bu" 4
\&\f(CW$minimized\fR = ipV6compress($ipV6_txt);
.Sp
Compress an ipV6 address to the minimum \s-1RFC\-1884\s0 format
.Sp
.Vb 2
\&  i.e.  FE80:02A0:0000:0000:0000:0000:0123:4567
\&  to    FE80:2A0::123:4567
.Ve
.IP "\(bu" 4
\&\f(CW$ipV6_txt\fR = inet_ntop($naddr6)
.Sp
.Vb 1
\&  Returns a minimized RFC\-1884 IPV6 address
.Ve
.IP "\(bu" 4
\&\f(CW$naddr6\fR = inet_pton($ipV6_txt);
.Sp
Takes an IPv6 text address of the form described in rfc1884
and returns a naddr6 128 bit binary address string in network order.
.IP "\(bu" 4
\&\f(CW$cidr\fR = mask2cidr($naddrmsk);
.IP "\(bu" 4
\&\fI\->mask2cidr($naddrmsk);\fR
.Sp
Returns the \s-1CIDR\s0 (prefix length) for the netmask \f(CW$naddrmsk\fR.
.Sp
May be called as a \s-1FUNCTION\s0 or a \s-1METHOD.\s0
.IP "\(bu" 4
\&\f(CW$mac_txt\fR = mac_bin2hex($bin_mac);
.IP "\(bu" 4
\&\fI\->\f(BImac_bin2hex()\fI;\fR
.Sp
Converts a binary \s-1MAC\s0 address into hex text.
.Sp
.Vb 1
\&  i.e. A1:B2:C3:D4:E5:F6
.Ve
.Sp
May be called as a \s-1FUNCTION\s0 or a \s-1METHOD.\s0
.IP "\(bu" 4
\&\f(CW$type\fR = type($naddr6);
.IP "\(bu" 4
\&\fI\->type($naddr6);\fR
.Sp
\&\fBipV6\fR method. Returns attributes of an \s-1IPV6\s0 address that may be tested
with the bit masks described in detail in the \s-1METHOD\s0 section above.
.Sp
May be called as a \s-1FUNCTION\s0 or a \s-1METHOD\s0 with an \f(CW$naddr6\fR argument.
.IP "\(bu" 4
\&\f(CW$scope\fR = scope($naddr6);
.IP "\(bu" 4
\&\fI\->scope($naddr6);\fR
.Sp
Returns the \s-1RFC\-2373\s0 scope of an \s-1IPV6\s0 address that may be equated module
constants described in detail in the \s-1METHOD\s0 section above.
.Sp
May be called as a \s-1FUNCTION\s0 or a \s-1METHOD\s0 with an \f(CW$naddr6\fR argument.
.IP "\(bu" 4
\&\f(CW$symbolptr\fR = \fBnet_symbols()\fR;
.Sp
Returns a hash containing most of the network symbols available for this
architecture.
.Sp
.Vb 4
\&  where $symbolptr = {
\&        SYMBOL_TEXT => value,
\&        ...
\&  };
.Ve
.Sp
Most all of these symbols have both a numeric and text value. Perl does the
\&\fBright\fR thing and uses the numeric value in all logic and arithmetic
operations and provides the text value for print requests.
.Sp
To print the numeric value:
.Sp
.Vb 1
\&  print (0 + &SYMBOL),"\en";
\&
\&  i.e.  print (0 + AF_INET()),"\en";
.Ve
.Sp
results in the digit \fB2\fR being printed, whereas:
.Sp
.Vb 1
\&        print AF_INET,"\en";
.Ve
.Sp
results in the string "\fBinet\fR" being printed.
.Sp
.Vb 2
\&  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...
.Ve
.SH "PREREQUISITES"
.IX Header "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 \s-1NOT\s0 come with these libraries installed.
.PP
Your build system must have a fully populated directory
.PP
.Vb 1
\&    /usr/include/sys
.Ve
.PP
Missing header files in the above directory will produce errors saying that
symbols such as \s-1AF_INET\s0 and \s-1PF_INET\s0 are missing.
.SH "ACKNOWLEDGEMENTS"
.IX Header "ACKNOWLEDGEMENTS"
This version of Net::Interface has been completely rewritten and updated to
include support for \s-1IPV6.\s0 Credit should be given to the original author
.PP
.Vb 1
\&        Stephen Zander <gibreel@pobox.com>
.Ve
.PP
for conceiving the idea behind Net::Interface and to the work done by
.PP
.Vb 1
\&        Jerrad Pierce jpierce@cpan.org
.Ve
.PP
on the maintenance and improvements to the original version.
.PP
Thanks also go to
.PP
.Vb 1
\&        Jens Rehsack <rehsack@web.de>
.Ve
.PP
for inspiring me to create this updated version and for his assistance in
vetting the design concepts and loads of other helpful things.
.PP
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.
.PP
.Vb 1
\&    file:              functions:
\&
\&  miniSocketXS.c  inet_aton, inet_ntoa
.Ve
.PP
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 \s-1PERL\s0 possible for all of us.
.SH "COPYRIGHT  2008\-2016 Michael Robinton <michael@bizsystems.com>"
.IX Header "COPYRIGHT 2008-2016 Michael Robinton <michael@bizsystems.com>"
All rights reserved.
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of either:
.PP
.Vb 3
\&  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.
.Ve
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See either
the \s-1GNU\s0 General Public License or the Artistic License for more details.
.PP
You should have received a copy of the Artistic License with this
distribution, in the file named \*(L"Artistic\*(R".  If not, I'll be glad to provide one.
.PP
You should also have received a copy of the \s-1GNU\s0 General Public License
along with this program in the file named \*(L"Copying\*(R". If not, write to the
.PP
.Vb 3
\&        Free Software Foundation, Inc.
\&        59 Temple Place, Suite 330
\&        Boston, MA  02111\-1307, USA
.Ve
.PP
or visit their web page on the internet at:
.PP
.Vb 1
\&        http://www.gnu.org/copyleft/gpl.html.
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBifconfig\fR\|(8), Net::Interface::NetSymbols,
Net::Interface::Developer