Interface(3pm)

📦
version 1.016 · 6 versions
, in ubuntu stonking

💖 Interface(3pm) — the Net::Interface glow-up 💖

so this whole page is the manual for Interface(3pm) out of the User Contributed Perl Documentation, and it's literally all about the Perl module Net::Interface. grab a snack, bestie, there's a lot of tea here 🍓

✨ NAME ✨

Net::Interface — a Perl extension to access network interfaces. that's the whole name, short and iconic 🎀

🌸 SYNOPSIS 🌸

here's how you pull it in, with every single import, no skipping:

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.

and like, the rest of the tag lore:

  • :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 — it's giving throwback, do not recommend 💀

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. it's the receipts, fr fr 📜

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);

and to make sure you lock in the current string case behavior even if the default changes someday:

use Net::Interface qw(:upper);

🛠️ FUNCTIONS and METHODS

okay bestie, here's the whole menu of calls — every line, exactly as written:

@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);

that WARNING API CHANGE !? yeah, that's the drama, we'll get to it later 💅

💜 DESCRIPTION 💜

Net::Interface is a module that lets you access 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. glow up 🦋✨

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. periodt.

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. it's not being shady, it's just built different 😭

🌈 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 retrieve 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. yes, again and again, main character energy only 🔁

🧚 SYMBOLS 🧚

Net::Interface provides 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 used 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. lowkey a plot twist 😮

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. 💀 classic

If you do not use strict; (not recommended, bestie, pls) 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. like, actually check, don't just vibe through it 😭

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 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. (yes, the deep dive is coming, we're not there yet 🍿)

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();

okay that's the lore drop so far — the address drama, the symbol rules, all of it. the rest of the manual is right behind this 💜

  • ->interfaces(); — bestie this one serves you a whole list of interface objects, one for each interface that supports IPV4 or IPV6. 🦋

On failure, it returns an empty list. Periodt.

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(); — not me having multiple calling invocations 😭✨ This method will refresh the data for an existing interface OR it can modify an existing interface OR it can create a new interface or alias.
    • $this_if = ->new('eth0'); — literally the same deal as ->interfaces above except you're naming one single known interface. You get an interface object back for the specific logical device you asked for. 💅

On failure return undef

  • $refresh_if = ->new(); — a new (refreshed) interface object is returned for the same logical device. Same device, fresh data, iconic. 🔥
  • $new_if = ->new(%iface_spec);
  • $new_if = ->new(\%iface_spec); — a logical device is created or updated. The specification lives in a hash table that you pass to new either directly or as a reference.

The interface specification is architecture dependent. For example, adding an address to an existing interface. (iykyk 🌸)

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. So it's giving side-address energy, not replacement energy. 🎀

  • $refresh_if = ->delete($naddr); — removes an address from an interface, where supported. 🧚
  • ->name(); — returns the name of the interface. That's it, that's the whole method, and honestly? Slay.
  • ->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, bestie. 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, sitting in matching positions in the returned array. Matching fits, matching energy. 💜
  • ->destination([$family],[$index]);
  • ->broadcast([$family],[$index]); — these two 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. Glow-up for your NIC fr fr. ✨

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. Two totally different girlies, do not mix them up. 🙈

There is no provision to SET the index. It is what it is.

  $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 ✨

okay so unless it says otherwise, when any of these methods error out they hand you back either undef or an empty array, depending on what kind of return you were expecting. context is everything bestie 💅

  • $naddr = inet_aton($host or $dotquad); — takes a hostname or a dotquad ipV4 address and turns it into a packed network address. glow up, but for bytes ✨
  • $dotquad = inet_ntoa($naddr); — the reverse vibe: binary IPV4 address goes in, dotquad text string comes out 🎀
  • $ipV6_txt = full_inet_ntop($naddr6); — gives you an uncompressed text string for a net6 address, like:
i.e.   FE80:02A0:0000:0000:0000:0000:0123:4567
  • $minimized = ipV6compress($ipV6_txt); — squishes an ipV6 address down to the minimum RFC-1884 format, no cap:
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 in the form described in rfc1884 and gives you back a naddr6 128 bit binary address string, in network order. iconic 🫶
  • $cidr = mask2cidr($naddrmsk);
  • ->mask2cidr($naddrmsk); — returns the CIDR (prefix length) for the netmask $naddrmsk. you can call it as a FUNCTION or as a METHOD, your choice, main character energy 💜
  • $mac_txt = mac_bin2hex($bin_mac);
  • ->mac_bin2hex(); — converts a binary MAC address into hex text, like:
i.e. A1:B2:C3:D4:E5:F6

and yes, you can call it as a FUNCTION or a METHOD 🌸

  • $type = type($naddr6);
  • ->type($naddr6); — ipV6 method. returns attributes of an IPV6 address, and you can test those with the bit masks described in detail up in the METHOD section. callable as a FUNCTION or a METHOD with an $naddr6 argument 💖
  • $scope = scope($naddr6);
  • ->scope($naddr6); — returns the RFC-2373 scope of an IPV6 address, and you can equate it against the module constants described in detail up in the METHOD section. also callable as a FUNCTION or a METHOD with an $naddr6 argument ✨
  • $symbolptr = net_symbols(); — returns a hash holding most of the network symbols available for this architecture, and it looks like this:
where $symbolptr = {
      SYMBOL_TEXT => value,
      ...
};

most all of these symbols have both a numeric value and a text value. Perl does the right thing and uses the numeric value in all logic and arithmetic operations, while handing you the text value for print requests. so smart 🧚

to print the numeric value:

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

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

which prints the digit 2. whereas:

        print AF_INET,"\n";

prints the string "inet". two vibes, one symbol 💫

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 you need kernel development libriaries installed on the build system, fr fr. systems like Ubuntu, FreeBSD, etc... do NOT come with these libraries installed. crying 😭

your build system must have a fully populated directory:

/usr/include/sys

missing header files in that directory will produce errors saying symbols such as AF_INET and PF_INET are missing. so if you see that, that's the tea 💀

👑 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. respectfully 🙏

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 💜

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:

  1. the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version, or
  2. 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. (yes that's the scary all-caps part, bestie, and it means what it says 😤)

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

and that's the whole page babes 💅 this beauty lives in perl v5.42.3, dated 2026-08-19, and it's Interface(3pm) — go forth and network, you absolute icon 👑✨ no cap.

📦 where this page comes from