NAME
Net::MAC - Perl extension for representing and manipulating MAC
addresses
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
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.
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
);
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.
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
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
AUTHOR
Karl Ward <karlward@cpan.org>
MAINTAINER
Oliver Gorwits <oliver.gorwits@oucs.ox.ac.uk>
CONTRIBUTORS
Oliver Gorwits, Robin Crook, Kevin Brintnall
COPYRIGHT AND LICENSE
Copyright (C) 2005-2008 Karl Ward <karlward@cpan.org>
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2 of the License, or (at your
option) any later version.
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 the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA