Net::MAC(3pm)

💖 NAME 💖

okay so welcome to Net::MAC(3pm) bestie — it's a Perl extension for representing and manipulating MAC addresses. yes, the MAC addresses. we're doing networking today and we're gonna slay it ✨

---

🌈 VERSION 🌈

version 2.103622 — she's got a version number that looks like a MAC address and honestly? iconic 👑

---

🎀 SYNOPSIS 🎀

lowkey just look at her go:

use Net::MAC;
my $mac = Net::MAC->new('mac' => '08:20:00:AB:CD:EF');

# Example: convert to a different MAC address format (dotted-decimal)
my $dec_mac = $mac->convert(
    'base' => 10,         # convert from base 16 to base 10
    'bit_group' => 8,     # octet grouping
    'delimiter' => '.'    # dot-delimited
);

print "$dec_mac\n"; # Should print 8.32.0.171.205.239

# Example: find out whether a MAC is base 16 or base 10
my $base = $mac->get_base();
if ($base == 16) {
    print "$mac is in hexadecimal format\n";
}
elsif ($base == 10) {
    print "$mac is in decimal format\n";
}
else { die "This MAC is neither base 10 nor base 16"; }

---

🦋 DESCRIPTION 🦋

so this is a module that lets you:

• store a MAC address in a Perl object 💾
• find out information about a stored MAC address 🔍
• convert a MAC address into a specified format 🔄
• easily compare two MAC addresses for string or numeric equality ⚖️

fr fr, there are SO many ways a MAC address can show up in text form and it's kind of a mess. the most common one is arguably colon-delimited octets in hexadecimal. but when you're hanging out with Cisco devices, you're way more likely to run into dot-delimited 16-bit groups in hexadecimal. over in the Windows world? addresses are usually dash-delimited octets in hexadecimal. MAC addresses in a Sun ethers file are usually non-zero-padded, colon-delimited hexadecimal octets. and sometimes you just stumble across dot-delimited octets in decimal form (certain Cisco SNMP MIBS actually use this, no cap). so yeah — hence the need for a common way to represent and manipulate MAC addresses in Perl 🫶

ngl there is a surprising amount of complexity hiding inside converting MAC addresses between types. this module does not attempt to understand all possible ways of representing a MAC address in a string, though most of the common ways of representing MAC addresses are supported. she's doing her best 💅

---

✨ METHODS ✨

💜 new() method (constructor)

the new() method creates a new Net::MAC object. the possible arguments are:

• mac — a string representing a MAC address
• base — a number corresponding to the numeric base of the MAC; possible values: 10 16
• delimiter — the delimiter in the MAC address string from above; possible values: : - . space
• bit_group — the number of bits between each delimiter; possible values: 8 16 48
• zero_padded — whether bit groups have leading zero characters (Net::MAC only allows zero-padding for bit groups of 8 bits); possible values: 0 1
• format — the name of a MAC address format specification which takes the place of the base, delimiter, bit_group and zero_padded options above
• verbose — write informational messages (useful for debugging); possible values: 0 1
• die — die() on invalid MAC address (default is to die on invalid MAC); possible values: 0 1 (default is 1)

when you call new() with a 'mac' argument and literally nothing else, the object will try to auto-discover metadata like bit grouping, number base, delimiter, etc. 🔎 and if the MAC is in an invalid or unknown format, the object will call the croak() function 😭 if you do not want the object to croak(), you can hand the new() method a die argument, like this:

my $m_obj = Net::MAC->new('mac' => '000adf012345', 'die' => 0);

there are cases where the auto-discovery just cannot guess the numeric base of a MAC, and honestly? relatable, sometimes you need a hint. if that happens, try giving the new() method a hint, like so:

# Example: this MAC is actually in decimal-dotted notation, not hex
my $mac = Net::MAC->new('mac' => '10.0.0.12.14.8', 'base' => 10);

this is necessary for cases like the one above, where the class has no way of knowing that an address is decimal instead of hexadecimal. it's giving "mystery address" 🙈

if you have installed a custom MAC address format into the class (see below) then you can also pass the "format" option as a hint:

my $mac = Net::MAC->new('mac' => 'ab01~ab01~ab01', 'format' => 'My_Format');

🌸 class methods 🌸

🧚 set_format_for()

when discovering MAC address formats, and converting between different formats (using "convert" or "as_*") the module can use predefined common formats or you can install your own for local circumstances 💫

for example consider a fictional device which uses MAC addresses formatted like "ab01~ab01~ab01", which would otherwise not be understood. you can install a new Format for this address style:

Net::MAC->set_format_for( 'My_Format_Name' => {
    base => 16,
    bit_group => 16,
    delimiter => '~',
});

now when using either the "format" option to "new()", or the "convert()" or "as_*" methods, the module will recognise this new format "My_Format_Name". the Hashref supplied can include any of the standard options for formats as listed elsewhere in this documentation 👑

my $mac = Net::MAC->new('mac' => 'ab01~ab01~ab01', 'format' => 'My_Format_Name');

⚠️ heads up bestie: custom formats sharing the same name as one shipping with the module (such as "Cisco") will override that built-in format. yes, you have that power now 💅

🌺 accessor methods 🌺

💖 get_mac() method

returns the MAC address stored in the object.

💖 get_base() method

returns the numeric base of the MAC address. there are two possible return values:

16    hexadecimal (common)
10    decimal (uncommon)

💖 get_delimiter() method

returns the delimiter, if any, in the specified MAC address. a valid delimiter matches the following regular expression:

/\:|\-|\.|\s/

in other words, either a colon, a dash, a dot, or a space ✨ if there is no delimiter, this method will return the undefined value (undef). if an invalid delimiter is found (like an asterisk or something), the object will call the croak() function 😭

💖 get_bit_group() method

returns the number of bits between the delimiters. a MAC address is a 48 bit address, usually delimited into 8 bit groupings (called octets), i.e.

08:20:00:AB:CD:EF

sometimes, MAC addresses are specified with fewer than 5 delimiters, or even no delimiters at all:

0820.00ab.cdef    # get_bit_group() returns 16
082000abcdef      # get_bit_group() returns 48, no delimiters at all

💖 get_zero_padded() method

returns a boolean value indicating whether or not the bit groups are zero-padded. a return value of 0 (false) means that the bit groups are not zero-padded, and a return value of 1 (true) means that they are zero-padded:

00.80.02.ac.4f.ff     # get_zero_padded() returns 1
0:80:2:ac:4f:ff       # get zero_padded() returns 0
0.125.85.122.155.64   # get_zero_padded() returns 0

🫶 reminder: Net::MAC only allows bit groups of 8 bits to be zero-padded.

🔥 convert() method 🔥

convert an already-defined Net::MAC object into a different MAC address format. with this function you can change the delimiter, the bit grouping, or the numeric base 🔄

# Example: convert to a different MAC address format (dotted-decimal)
my $new_mac_obj = $existing_mac_obj->convert(
        'base' => 16,         # convert to base 16, if necessary
        'bit_group' => 16,    # 16 bit grouping
        'delimiter' => '.'    # dot-delimited
);

note that if any of the above arguments are not provided, they will be set to the following default values:

base       16
bit_group  8  (i.e. a delimiter will be used)
delimiter  :

⭐ Conversion to common formats ⭐

the most common formats have shortcut conversion methods that can be used instead of the convert() method with its many options. yes, she has shortcuts, because she's efficient 💅

🍓 as_Cisco() method

Cisco routers seem to usually represent MAC addresses in hexadecimal, dot-delimited, 16 bit groups.

my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF');
my $cisco_mac = $mac->as_Cisco();
print "$cisco_mac";
# should print 0002.03aa.abff

🍓 as_IEEE() method

the IEEE 802 2001 specification represents MAC addresses in hexadecimal, colon-delimited, upper case, 8 bit groups.

my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF');
my $IEEE_mac = Net::MAC->as_IEEE();
print "$IEEE_mac";
# should print 00:02:03:AA:AB:FF

🍓 as_Microsoft() method

Microsoft usually represents MAC addresses in hexadecimal, dash delimited, upper case, 8 bit groups.

my $mac = Net::MAC->new(mac => '00:02:03:AA:AB:FF');
my $microsoft_mac = $mac->as_Microsoft();
print "$microsoft_mac";
# should print 00-02-03-AA-AB-FF

🍓 as_Sun() method

Sun represents MAC addresses in hexadecimal, colon-delimited, non-zero-padded, lower case, 8 bit groups.

my $mac = Net::MAC->new(mac => '00-02-03-AA-AB-FF');
my $sun_mac = $mac->as_Sun();
print "$sun_mac";
# should print 0:2:3:aa:ab:ff

🌟 Stringification 🌟

the stringification operator "" has been overloaded to allow for the meaningful use of the instance variable in a string. she's literally just a string now and she's thriving 💖

my $mac = Net::MAC->new(mac => '00:0a:23:4f:ff:ef');
print "object created for MAC address $mac";
# Should print:
# object created for MAC address 00:0a:23:4f:ff:ef

🌈 MAC address comparison 🌈

the Perl operators 'eq' and 'ne' (string comparison) and '==' '!=' (numeric comparison) have been overloaded to allow simple, meaningful comparisons of two MAC addresses. main character energy, honestly 👑

example (two MAC addresses numerically identical but in different formats):

my $d = Net::MAC->new(mac => '0.8.1.9.16.16', base => 10);
my $h = Net::MAC->new(mac => '00:08:01:0A:10:10', base => 16);
if ($d == $h) { print "$d and $h are numerically equal"; }
if ($d ne $h) { print " but $d and $h are not the same string"; }

---

💀 BUGS 💀

😭 Malformed MAC addresses

Net::MAC can't handle MAC addresses where whole leading zero octets are omitted. example:

7.122.32.41.5 (should be 0.7.122.32.41.5)

arguably, that's their problem and not mine, but maybe someday I'll get around to supporting that case as well 🙈

😭 Case is not preserved

Net::MAC doesn't reliably preserve case in a MAC address. I might add a flag to the new() and convert() methods to do this. I might not.

case is however altered when using the as_foo() formatted output methods.

---

🔍 SEE ALSO 🔍

Net::MacMap Net::MAC::Vendor

---

👑 MAINTAINER 👑

Oliver Gorwits <oliver@cpan.org>

---

🫶 CONTRIBUTORS 🫶

Oliver Gorwits, Robin Crook, Kevin Brintnall

---

🎀 AUTHOR 🎀

Karl Ward <karlward@cpan.org>

💖 COPYRIGHT AND LICENSE 💖

Okay so legal bit, bestie, but it's short and it's giving ✨formal✨ so let's do this properly:

This software is Copyright (c) 2010 by Karl Ward <karlward@cpan.org>. 🫶

That's the whole vibe. One guy, one year, one email address, iconic behavior honestly.

---

And this is free software, licensed under:

The GNU General Public License, Version 2, June 1991

Free software, no cap. GPLv2, June 1991, the classic. Read the license if you need the deets, because that's the actual binding thing and not me being cute in a terminal 💅

---

And that's a wrap on Net::MAC! 🎀 The source and version for this lil doc drop are perl v5.36.0, dated 2022-12-04, from the Net::MAC(3pm) man page — so yeah, that's the era of Perl we're living in, and honestly? Slay. Go forth and parse some MAC addresses, bestie 🦋💜