/ 
Net-MAC-1.1
River stage one • 1 direct dependent • 1 total dependent
/ Net::MAC

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->get_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->get_mac(), " is in hexadecimal format\n"; 
  } 
  elsif ($base == 10) { 
	  print $mac->get_mac(), " is in decimal format\n"; 
  }
  else { die "This MAC is invalid"; }

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

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 the totally insane 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
  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

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

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.

Zero-padding is not configurable

Net::MAC doesn't allow you to specify whether or not bit groups should be zero-padded. It always writes out base 16 addresses as zero-padded. Example:

You supply '8.32.0.171.205.239' and you want '8:20:0:ab:cd:ef'.  
Net::MAC gives you '08:20:00:ab:cd:ef' and a kick in the face.

I'll probably add support for configurable zero-padding.

SEE ALSO

Net::MacMap Net::MAC::Vendor

AUTHOR

Karl Ward <karlward@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2005 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