NAME¶
Net::MAC - Perl extension for representing and manipulating MAC addresses
VERSION¶
version 2.103622
SYNOPSIS¶
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¶
This is a module that allows you to
- 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
There are quite a few different ways that MAC addresses may be represented in
textual form. The most common is arguably colon-delimited octets in
hexadecimal form. When working with Cisco devices, however, you are more
likely to encounter addresses that are dot-delimited 16-bit groups in
hexadecimal form. In the Windows world, addresses are usually dash-delimited
octets in hexadecimal form. MAC addresses in a Sun ethers file are usually
non-zero-padded, colon-delimited hexadecimal octets. And sometimes, you come
across dot-delimited octets in decimal form (certain Cisco SNMP MIBS actually
use this). Hence the need for a common way to represent and manipulate MAC
addresses in Perl.
There is a surprising amount of complexity involved in 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.
METHODS¶
new() method (constructor)¶
The
new() method creates a new Net::MAC object. 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 the
new() method is called with a 'mac' argument and nothing else,
the object will attempt to auto-discover metadata like bit grouping, number
base, delimiter, etc. If the MAC is in an invalid or unknown format, the
object will call the
croak() function. If you don't want the object to
croak(), you can give the
new() method a die argument, such as:
my $m_obj = Net::MAC->new('mac' => '000adf012345', 'die' => 0);
There are cases where the auto-discovery will not be able to guess the numeric
base of a MAC. If this 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.
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');
Custom formats sharing the same name as one shipping with the module (such as
"Cisco") will override that built-in format.
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
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 :
The most common formats have shortcut conversion methods that can be used
instead of the
convert() method with its many options.
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.
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.
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¶
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¶
This software is Copyright (c) 2010 by Karl Ward <karlward@cpan.org>.
This is free software, licensed under:
The GNU General Public License, Version 2, June 1991