1 files changed, 52 insertions, 30 deletions

diff --git a/src/lib/libc/net/ethers.3 b/src/lib/libc/net/ethers.3
index 81e6c65935..041ee981ec 100644
--- a/src/lib/libc/net/ethers.3
+++ b/src/lib/libc/net/ethers.3
@@ -1,65 +1,87 @@
+.\"     $OpenBSD: ethers.3,v 1.21 2011/04/19 22:38:26 matthew Exp $
 .\"
 .\" Written by roland@frob.com.  Public domain.
 .\"
-.Dd December 16, 1993
+.Dd $Mdocdate: April 19 2011 $
 .Dt ETHERS 3
-.Os NetBSD
+.Os
 .Sh NAME
+.Nm ether_aton ,
 .Nm ether_ntoa ,
-.Nm ether_addr ,
 .Nm ether_ntohost ,
 .Nm ether_hostton ,
-.Nm ether_line ,
+.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 "char *s"
+.Fn ether_aton "const char *s"
+.Ft int
 .Fn ether_ntohost "char *hostname" "struct ether_addr *e"
-.Fn ether_hostton "char *hostname" "struct ether_addr *e"
-.Fn ether_line "char *l" "struct ether_addr *e" "char *hostname"
+.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 
+Ethernet addresses are represented by the
 following structure:
 .Bd -literal -offset indent
 struct ether_addr {
-        u_char  ether_addr_octet[6];
+        u_int8_t  ether_addr_octet[6];
 };
 .Ed
 .Pp
 The
 .Fn ether_ntoa
-function converts this structure into an ASCII string of the form
-``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.
+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 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.
+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 data base mapping host names to Ethernet
+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.
+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 + appears alone on a line in the file, then
+.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
@@ -73,9 +95,13 @@ The
 .Fn ether_line
 function parses a line from the
 .Pa /etc/ethers
-file and fills in the passed ``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.
+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
@@ -91,12 +117,8 @@ The
 and
 .Fn ether_line
 functions were adopted from SunOS and appeared in
-NetBSD 0.9b.
+.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.  There is no way to restrict how many
-character will be written into the host name buffer passed.  A very
-long line in
-.Pa /etc/ethers
-could overflow your buffer.
+these functions overwrite it.