Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::MAC(3)	      User Contributed Perl Documentation	   Net::MAC(3)

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  :

   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

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

perl v5.24.1			  2010-12-28			   Net::MAC(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | BUGS | SEE ALSO | MAINTAINER | CONTRIBUTORS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::MAC&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help