.\"	$OpenBSD: ethers.3,v 1.21 2011/04/19 22:38:26 matthew Exp $
.\"
.\" Written by roland@frob.com.  Public domain.
.\"
.Dd $Mdocdate: April 19 2011 $
.Dt ETHERS 3
.Os
.Sh NAME
.Nm ether_aton ,
.Nm ether_ntoa ,
.Nm ether_ntohost ,
.Nm ether_hostton ,
.Nm ether_line
.Nd get ethers entry
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/socket.h>
.Fd #include <net/if.h>
.Fd #include <netinet/in.h>
.Fd #include <netinet/if_ether.h>
.Ft char *
.Fn ether_ntoa "struct ether_addr *e"
.Ft struct ether_addr *
.Fn ether_aton "const char *s"
.Ft int
.Fn ether_ntohost "char *hostname" "struct ether_addr *e"
.Ft int
.Fn ether_hostton "const char *hostname" "struct ether_addr *e"
.Ft int
.Fn ether_line "const char *l" "struct ether_addr *e" "char *hostname"
.Sh DESCRIPTION
Ethernet addresses are represented by the
following structure:
.Bd -literal -offset indent
struct ether_addr {
        u_int8_t  ether_addr_octet[6];
};
.Ed
.Pp
The
.Fn ether_ntoa
function converts this structure into an
.Tn ASCII
string of the form
.Dq xx:xx:xx:xx:xx:xx ,
consisting of 6 hexadecimal numbers separated
by colons.
It returns a pointer to a static buffer that is reused for each call.
The
.Fn ether_aton
converts an
.Tn ASCII
string of the same form and to a structure
containing the 6 octets of the address.
It returns a pointer to a static structure that is reused for each call.
.Fn ether_aton
will return NULL if the string does not represent a valid address.
.Pp
The
.Fn ether_ntohost
and
.Fn ether_hostton
functions interrogate the database mapping host names to Ethernet
addresses,
.Pa /etc/ethers .
The
.Fn ether_ntohost
function looks up the given Ethernet address and writes the associated
host name into the character buffer passed.
This buffer should be
.Dv MAXHOSTNAMELEN
characters in size.
The
.Fn ether_hostton
function looks up the given host name and writes the associated
Ethernet address into the structure passed.
Both functions return
zero if they find the requested host name or address, and \-1 if not.
.Pp
Each call reads
.Pa /etc/ethers
from the beginning; if a
.Ql +
appears alone on a line in the file, then
.Fn ether_hostton
will consult the
.Pa ethers.byname
YP map, and
.Fn ether_ntohost
will consult the
.Pa ethers.byaddr
YP map.
.Pp
The
.Fn ether_line
function parses a line from the
.Pa /etc/ethers
file and fills in the passed
.Li struct ether_addr
and character buffer with the Ethernet address and host name on the line.
It returns zero if the line was successfully parsed and \-1 if not.
The character buffer should be
.Dv MAXHOSTNAMELEN
characters in size.
.Sh FILES
.Bl -tag -width /etc/ethers -compact
.It Pa /etc/ethers
.El
.Sh SEE ALSO
.Xr ethers 5
.Sh HISTORY
The
.Fn ether_ntoa ,
.Fn ether_aton ,
.Fn ether_ntohost ,
.Fn ether_hostton ,
and
.Fn ether_line
functions were adopted from SunOS and appeared in
.Nx 0.9b .
.Sh BUGS
The data space used by these functions is static; if future use
requires the data, it should be copied before any subsequent calls to
these functions overwrite it.