1 files changed, 124 insertions, 0 deletions

diff --git a/src/lib/libc/net/ethers.3 b/src/lib/libc/net/ethers.3
new file mode 100644
index 0000000000..aa7249dc47
--- /dev/null
+++ b/src/lib/libc/net/ethers.3
@@ -0,0 +1,124 @@
+.\"     $OpenBSD: ethers.3,v 1.20 2008/12/07 10:10:33 weerd Exp $
+.\"
+.\" Written by roland@frob.com.  Public domain.
+.\"
+.Dd $Mdocdate: December 7 2008 $
+.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.9 b.
+.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.