.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Net::MAC 3pm"
.TH Net::MAC 3pm "2022-12-04" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::MAC \- Perl extension for representing and manipulating MAC addresses
.SH "VERSION"
.IX Header "VERSION"
version 2.103622
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  use Net::MAC;
\&  my $mac = Net::MAC\->new(\*(Aqmac\*(Aq => \*(Aq08:20:00:AB:CD:EF\*(Aq); 
\&
\&  # Example: convert to a different MAC address format (dotted\-decimal)
\&  my $dec_mac = $mac\->convert(
\&      \*(Aqbase\*(Aq => 10,         # convert from base 16 to base 10
\&      \*(Aqbit_group\*(Aq => 8,     # octet grouping
\&      \*(Aqdelimiter\*(Aq => \*(Aq.\*(Aq    # dot\-delimited
\&  ); 
\&
\&  print "$dec_mac\en"; # 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\en"; 
\&  } 
\&  elsif ($base == 10) { 
\&      print "$mac is in decimal format\en"; 
\&  }
\&  else { die "This MAC is neither base 10 nor base 16"; }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a module that allows you to
.PP
.Vb 4
\&  \- 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
.Ve
.PP
There are quite a few different ways that \s-1MAC\s0 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.  \s-1MAC\s0 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 \s-1SNMP MIBS\s0 actually use this). Hence the need for a common way to 
represent and manipulate \s-1MAC\s0 addresses in Perl.
.PP
There is a surprising amount of complexity involved in converting \s-1MAC\s0 
addresses between types.  This module does not attempt to understand all 
possible ways of representing a \s-1MAC\s0 address in a string, though most of the 
common ways of representing \s-1MAC\s0 addresses are supported.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fBnew()\fP method (constructor)"
.IX Subsection "new() method (constructor)"
The \fBnew()\fR method creates a new Net::MAC object.  Possible arguments are
.PP
.Vb 10
\&  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)
.Ve
.PP
When the \fBnew()\fR 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 \s-1MAC\s0 is in an invalid or unknown format, the object 
will call the \fBcroak()\fR function.  If you don't want the object to \fBcroak()\fR, 
you can give the \fBnew()\fR method a die argument, such as:
.PP
.Vb 1
\&  my $m_obj = Net::MAC\->new(\*(Aqmac\*(Aq => \*(Aq000adf012345\*(Aq, \*(Aqdie\*(Aq => 0);
.Ve
.PP
There are cases where the auto-discovery will not be able to guess the 
numeric base of a \s-1MAC.\s0  If this happens, try giving the \fBnew()\fR method 
a hint, like so:
.PP
.Vb 2
\&  # Example: this MAC is actually in decimal\-dotted notation, not hex
\&  my $mac = Net::MAC\->new(\*(Aqmac\*(Aq => \*(Aq10.0.0.12.14.8\*(Aq, \*(Aqbase\*(Aq => 10);
.Ve
.PP
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.
.PP
If you have installed a custom \s-1MAC\s0 address format into the class (see below)
then you can also pass the \f(CW\*(C`format\*(C'\fR option as a hint:
.PP
.Vb 1
\&  my $mac = Net::MAC\->new(\*(Aqmac\*(Aq => \*(Aqab01~ab01~ab01\*(Aq, \*(Aqformat\*(Aq => \*(AqMy_Format\*(Aq);
.Ve
.SS "class methods"
.IX Subsection "class methods"
\fI\f(BIset_format_for()\fI\fR
.IX Subsection "set_format_for()"
.PP
When discovering \s-1MAC\s0 address formats, and converting between different
formats (using \f(CW\*(C`convert\*(C'\fR or \f(CW\*(C`as_*\*(C'\fR) the module can use predefined common
formats or you can install your own for local circumstances.
.PP
For example consider a fictional device which uses \s-1MAC\s0 addresses formatted
like \f(CW\*(C`ab01~ab01~ab01\*(C'\fR, which would otherwise not be understood. You can
install a new Format for this address style:
.PP
.Vb 5
\&  Net::MAC\->set_format_for( \*(AqMy_Format_Name\*(Aq => {
\&      base => 16,
\&      bit_group => 16,
\&      delimiter => \*(Aq~\*(Aq,
\&  });
.Ve
.PP
Now when using either the \f(CW\*(C`format\*(C'\fR option to \f(CW\*(C`new()\*(C'\fR, or the \f(CW\*(C`convert()\*(C'\fR or
\&\f(CW\*(C`as_*\*(C'\fR methods, the module will recognise this new format \f(CW\*(C`My_Format_Name\*(C'\fR.
The Hashref supplied can include any of the standard options for formats as
listed elsewhere in this documentation.
.PP
.Vb 1
\&  my $mac = Net::MAC\->new(\*(Aqmac\*(Aq => \*(Aqab01~ab01~ab01\*(Aq, \*(Aqformat\*(Aq => \*(AqMy_Format_Name\*(Aq);
.Ve
.PP
Custom formats sharing the same name as one shipping with the module (such as
\&\f(CW\*(C`Cisco\*(C'\fR) will override that built-in format.
.SS "accessor methods"
.IX Subsection "accessor methods"
\fI\f(BIget_mac()\fI method\fR
.IX Subsection "get_mac() method"
.PP
Returns the \s-1MAC\s0 address stored in the object.
.PP
\fI\f(BIget_base()\fI method\fR
.IX Subsection "get_base() method"
.PP
Returns the numeric base of the \s-1MAC\s0 address.  There are two possible return 
values:
.PP
.Vb 2
\&  16    hexadecimal (common)
\&  10    decimal (uncommon)
.Ve
.PP
\fI\f(BIget_delimiter()\fI method\fR
.IX Subsection "get_delimiter() method"
.PP
Returns the delimiter, if any, in the specified \s-1MAC\s0 address.  A valid 
delimiter matches the following regular expression:
.PP
.Vb 1
\&  /\e:|\e\-|\e.|\es/
.Ve
.PP
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 \fBcroak()\fR function.
.PP
\fI\f(BIget_bit_group()\fI method\fR
.IX Subsection "get_bit_group() method"
.PP
Returns the number of bits between the delimiters.  A \s-1MAC\s0 address is a 48 bit 
address, usually delimited into 8 bit groupings (called octets), i.e.
.PP
.Vb 1
\&  08:20:00:AB:CD:EF
.Ve
.PP
Sometimes, \s-1MAC\s0 addresses are specified with fewer than 5 delimiters, or even 
no delimiters at all:
.PP
.Vb 2
\&  0820.00ab.cdef    # get_bit_group() returns 16
\&  082000abcdef      # get_bit_group() returns 48, no delimiters at all
.Ve
.PP
\fI\f(BIget_zero_padded()\fI method\fR
.IX Subsection "get_zero_padded() method"
.PP
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:
.PP
.Vb 3
\&  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
.Ve
.PP
Net::MAC only allows bit groups of 8 bits to be zero-padded.
.SS "\fBconvert()\fP method"
.IX Subsection "convert() method"
Convert an already-defined Net::MAC object into a different \s-1MAC\s0 address 
format.  With this function you can change the delimiter, the bit grouping, 
or the numeric base.
.PP
.Vb 6
\&  # Example: convert to a different MAC address format (dotted\-decimal)
\&  my $new_mac_obj = $existing_mac_obj\->convert(
\&          \*(Aqbase\*(Aq => 16,         # convert to base 16, if necessary
\&          \*(Aqbit_group\*(Aq => 16,    # 16 bit grouping
\&          \*(Aqdelimiter\*(Aq => \*(Aq.\*(Aq    # dot\-delimited
\&  );
.Ve
.PP
Note that if any of the above arguments are not provided, they will be set to
the following default values:
.PP
.Vb 3
\& base       16
\& bit_group  8  (i.e. a delimiter will be used)
\& delimiter  :
.Ve
.SS "Conversion to common formats"
.IX Subsection "Conversion to common formats"
The most common formats have shortcut conversion methods that can be used 
instead of the \fBconvert()\fR method with its many options.
.PP
\fI\f(BIas_Cisco()\fI method\fR
.IX Subsection "as_Cisco() method"
.PP
Cisco routers seem to usually represent \s-1MAC\s0 addresses in hexadecimal, 
dot-delimited, 16 bit groups.
.PP
.Vb 4
\&  my $mac = Net::MAC\->new(mac => \*(Aq00\-02\-03\-AA\-AB\-FF\*(Aq); 
\&  my $cisco_mac = $mac\->as_Cisco(); 
\&  print "$cisco_mac"; 
\&  # should print 0002.03aa.abff
.Ve
.PP
\fI\f(BIas_IEEE()\fI method\fR
.IX Subsection "as_IEEE() method"
.PP
The \s-1IEEE 802 2001\s0 specification represents \s-1MAC\s0 addresses in hexadecimal, 
colon-delimited, upper case, 8 bit groups.
.PP
.Vb 4
\&  my $mac = Net::MAC\->new(mac => \*(Aq00\-02\-03\-AA\-AB\-FF\*(Aq); 
\&  my $IEEE_mac = Net::MAC\->as_IEEE(); 
\&  print "$IEEE_mac"; 
\&  # should print 00:02:03:AA:AB:FF
.Ve
.PP
\fI\f(BIas_Microsoft()\fI method\fR
.IX Subsection "as_Microsoft() method"
.PP
Microsoft usually represents \s-1MAC\s0 addresses in hexadecimal, dash delimited, 
upper case, 8 bit groups.
.PP
.Vb 4
\&  my $mac = Net::MAC\->new(mac => \*(Aq00:02:03:AA:AB:FF\*(Aq); 
\&  my $microsoft_mac = $mac\->as_Microsoft(); 
\&  print "$microsoft_mac"; 
\&  # should print 00\-02\-03\-AA\-AB\-FF
.Ve
.PP
\fI\f(BIas_Sun()\fI method\fR
.IX Subsection "as_Sun() method"
.PP
Sun represents \s-1MAC\s0 addresses in hexadecimal, colon-delimited, 
non-zero-padded, lower case, 8 bit groups.
.PP
.Vb 4
\&  my $mac = Net::MAC\->new(mac => \*(Aq00\-02\-03\-AA\-AB\-FF\*(Aq); 
\&  my $sun_mac = $mac\->as_Sun(); 
\&  print "$sun_mac"; 
\&  # should print 0:2:3:aa:ab:ff
.Ve
.SS "Stringification"
.IX Subsection "Stringification"
The stringification operator "" has been overloaded to allow for the 
meaningful use of the instance variable in a string.
.PP
.Vb 4
\&  my $mac = Net::MAC\->new(mac => \*(Aq00:0a:23:4f:ff:ef\*(Aq); 
\&  print "object created for MAC address $mac"; 
\&  # Should print:
\&  # object created for MAC address 00:0a:23:4f:ff:ef
.Ve
.SS "\s-1MAC\s0 address comparison"
.IX Subsection "MAC address comparison"
The Perl operators 'eq' and 'ne' (string comparison) and '==' '!=' (numeric 
comparison) have been overloaded to allow simple, meaningful comparisons of 
two \s-1MAC\s0 addresses.
.PP
Example (two \s-1MAC\s0 addresses numerically identical but in different formats):
.PP
.Vb 4
\&  my $d = Net::MAC\->new(mac => \*(Aq0.8.1.9.16.16\*(Aq, base => 10); 
\&  my $h = Net::MAC\->new(mac => \*(Aq00:08:01:0A:10:10\*(Aq, 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"; }
.Ve
.SH "BUGS"
.IX Header "BUGS"
.SS "Malformed \s-1MAC\s0 addresses"
.IX Subsection "Malformed MAC addresses"
Net::MAC can't handle \s-1MAC\s0 addresses where whole leading zero octets are 
omitted.  Example:
.PP
.Vb 1
\&  7.122.32.41.5 (should be 0.7.122.32.41.5)
.Ve
.PP
Arguably, that's their problem and not mine, but maybe someday I'll get 
around to supporting that case as well.
.SS "Case is not preserved"
.IX Subsection "Case is not preserved"
Net::MAC doesn't reliably preserve case in a \s-1MAC\s0 address.  I might add a 
flag to the \fBnew()\fR and \fBconvert()\fR methods to do this.  I might not.
.PP
Case is however altered when using the \fBas_foo()\fR formatted output methods.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::MacMap
Net::MAC::Vendor
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Oliver Gorwits <oliver@cpan.org>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Oliver Gorwits, Robin Crook, Kevin Brintnall
.SH "AUTHOR"
.IX Header "AUTHOR"
Karl Ward <karlward@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2010 by Karl Ward <karlward@cpan.org>.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The GNU General Public License, Version 2, June 1991
.Ve