1.\"	$MirOS: src/lib/libc/net/ethers.3,v 1.4 2005/09/22 20:40:02 tg Exp $
2.\"	$OpenBSD: ethers.3,v 1.16 2005/07/22 04:50:51 jaredy Exp $
3.\"
4.\" Written by roland@frob.com.  Public domain.
5.\"
6.Dd December 16, 1993
7.Dt ETHERS 3
8.Os
9.Sh NAME
10.Nm ether_aton ,
11.Nm ether_ntoa ,
12.Nm ether_addr ,
13.Nm ether_ntohost ,
14.Nm ether_hostton ,
15.Nm ether_line
16.Nd get ethers entry
17.Sh SYNOPSIS
18.Fd #include <sys/socket.h>
19.Fd #include <net/if.h>
20.Fd #include <netinet/in.h>
21.Fd #include <netinet/if_ether.h>
22.Ft char *
23.Fn ether_ntoa "struct ether_addr *e"
24.Ft struct ether_addr *
25.Fn ether_aton "const char *s"
26.Ft int
27.Fn ether_ntohost "char *hostname" "struct ether_addr *e"
28.Ft int
29.Fn ether_hostton "const char *hostname" "struct ether_addr *e"
30.Ft int
31.Fn ether_line "const char *l" "struct ether_addr *e" "char *hostname"
32.Sh DESCRIPTION
33Ethernet addresses are represented by the
34following structure:
35.Bd -literal -offset indent
36struct ether_addr {
37        u_int8_t  ether_addr_octet[6];
38};
39.Ed
40.Pp
41The
42.Fn ether_ntoa
43function converts this structure into an
44.Tn ASCII
45string of the form
46.Dq xx:xx:xx:xx:xx:xx ,
47consisting of 6 hexadecimal numbers separated
48by colons.
49It returns a pointer to a static buffer that is reused for each call.
50The
51.Fn ether_aton
52converts an
53.Tn ASCII
54string of the same form and to a structure
55containing the 6 octets of the address.
56It returns a pointer to a static structure that is reused for each call.
57.Pp
58The
59.Fn ether_ntohost
60and
61.Fn ether_hostton
62functions interrogate the database mapping host names to Ethernet
63addresses,
64.Pa /etc/ethers .
65The
66.Fn ether_ntohost
67function looks up the given Ethernet address and writes the associated
68host name into the character buffer passed.
69This buffer should be
70.Dv MAXHOSTNAMELEN
71characters in size.
72The
73.Fn ether_hostton
74function looks up the given host name and writes the associated
75Ethernet address into the structure passed.
76Both functions return
77zero if they find the requested host name or address, and \-1 if not.
78.Pp
79Each call reads
80.Pa /etc/ethers
81from the beginning.
82.Pp
83The
84.Fn ether_line
85function parses a line from the
86.Pa /etc/ethers
87file and fills in the passed
88.Li struct ether_addr
89and character buffer with the Ethernet address and host name on the line.
90It returns zero if the line was successfully parsed and \-1 if not.
91The character buffer should be
92.Dv MAXHOSTNAMELEN
93characters in size.
94.Sh FILES
95.Bl -tag -width /etc/ethers -compact
96.It Pa /etc/ethers
97.El
98.Sh SEE ALSO
99.Xr ethers 5
100.Sh HISTORY
101The
102.Fn ether_ntoa ,
103.Fn ether_aton ,
104.Fn ether_ntohost ,
105.Fn ether_hostton ,
106and
107.Fn ether_line
108functions were adopted from SunOS and appeared in
109.Nx 0.9 b.
110.Sh BUGS
111The data space used by these functions is static; if future use
112requires the data, it should be copied before any subsequent calls to
113these functions overwrite it.
114