Provided by: libnet-mac-perl_2.103622-2_all bug


       Net::MAC - Perl extension for representing and manipulating MAC addresses


       version 2.103622


         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

         # 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"; }


       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


   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' => '', '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

       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

         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:


       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.


       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:
     # get_zero_padded() returns 1
         0:80:2:ac:4f:ff       # get zero_padded() returns 0   # 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

       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 => '', 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"; }


   Malformed MAC addresses
       Net::MAC can't handle MAC addresses where whole leading zero octets are omitted.  Example:
 (should be

       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.


       Net::MacMap Net::MAC::Vendor


       Oliver Gorwits <>


       Oliver Gorwits, Robin Crook, Kevin Brintnall


       Karl Ward <>


       This software is Copyright (c) 2010 by Karl Ward <>.

       This is free software, licensed under:

         The GNU General Public License, Version 2, June 1991