'\" t
.\" Copyright, the authors of the Linux man-pages project
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH ether_aton 3 (date) "Linux man-pages (unreleased)"
.SH NAME
ether_aton, ether_ntoa, ether_ntohost, ether_hostton, ether_line,
ether_ntoa_r, ether_aton_r \- Ethernet address manipulation routines
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.B #include <netinet/ether.h>
.P
.BI "char *ether_ntoa(const struct ether_addr *" addr );
.BI "struct ether_addr *ether_aton(const char *" asc );
.P
.BI "int ether_ntohost(char *" hostname ", const struct ether_addr *" addr );
.BI "int ether_hostton(const char *" hostname ", struct ether_addr *" addr );
.P
.BI "int ether_line(const char *" line ", struct ether_addr *" addr ,
.BI "               char *" hostname );
.P
/* GNU extensions */
.BI "char *ether_ntoa_r(const struct ether_addr *" addr ", char *" buf );
.P
.BI "struct ether_addr *ether_aton_r(const char *" asc ,
.BI "                                struct ether_addr *" addr );
.fi
.SH DESCRIPTION
.BR ether_aton ()
converts the 48-bit Ethernet host address
.I asc
from the standard hex-digits-and-colons notation into binary data in
network byte order and returns a pointer to it in a statically
allocated buffer, which subsequent calls will
overwrite.
.BR ether_aton ()
returns NULL if the address is invalid.
.P
The
.BR ether_ntoa ()
function converts the Ethernet host address
.I addr
given in network byte order to a string in standard
hex-digits-and-colons notation, omitting leading zeros.
The string is returned in a statically allocated buffer,
which subsequent calls will overwrite.
.P
The
.BR ether_ntohost ()
function maps an Ethernet address to the
corresponding hostname in
.I /etc/ethers
and returns nonzero if it cannot be found.
.P
The
.BR ether_hostton ()
function maps a hostname to the
corresponding Ethernet address in
.I /etc/ethers
and returns nonzero if it cannot be found.
.P
The
.BR ether_line ()
function parses a line in
.I /etc/ethers
format
(ethernet address followed by whitespace followed by hostname;
\[aq]#\[aq] introduces a comment)
and returns an address and hostname pair,
or nonzero if it cannot be parsed.
The buffer pointed to by
.I hostname
must be sufficiently long
\[em]for example,
have the same length as
.IR line \[em].
.P
The functions
.BR ether_ntoa_r ()
and
.BR ether_aton_r ()
are reentrant
thread-safe versions of
.BR ether_ntoa ()
and
.BR ether_aton ()
respectively, and do not use static buffers.
.P
The structure
.I ether_addr
is defined in
.I <net/ethernet.h>
as:
.P
.in +4n
.EX
struct ether_addr {
    uint8_t ether_addr_octet[6];
}
.EE
.in
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR ether_aton (),
.BR ether_ntoa ()
T}	Thread safety	MT-Unsafe
T{
.na
.nh
.BR ether_ntohost (),
.BR ether_hostton (),
.BR ether_line (),
.BR ether_ntoa_r (),
.BR ether_aton_r ()
T}	Thread safety	MT-Safe
.TE
.SH STANDARDS
None.
.SH HISTORY
4.3BSD, SunOS.
.SH BUGS
In glibc 2.2.5 and earlier, the implementation of
.BR ether_line ()
.\" The fix was presumably commit c0a0f9a32c8baa6ab93d00eb42d92c02e9e146d7
.\" which was in glibc 2.3
is broken.
.SH SEE ALSO
.BR ethers (5)