lib/libc/net/ethers.3

   1 .\"     $NetBSD: ethers.3,v 1.13 2003/04/16 13:34:41 wiz Exp $
   2 .\"
   3 .\" Written by roland@frob.com.  Public domain.
   4 .\"
   5 .Dd November 2, 1997
   6 .Dt ETHERS 3
   7 .Os
   8 .Sh NAME
   9 .Nm ether_ntoa ,
  10 .Nm ether_aton ,
  11 .Nm ether_ntohost ,
  12 .Nm ether_hostton ,
  13 .Nm ether_line ,
  14 .Nd get ethers entry
  15 .Sh LIBRARY
  16 .Lb libc
  17 .Sh SYNOPSIS
  18 .In sys/types.h
  19 .In sys/socket.h
  20 .In net/if.h
  21 .In net/if_ether.h
  22 .Ft char *
  23 .Fn ether_ntoa "const 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" "const 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 *line" "struct ether_addr *e" "char *hostname"
  32 .Sh DESCRIPTION
  33 Ethernet addresses are represented by the
  34 following structure:
  35 .Bd -literal -offset indent
  36 struct ether_addr {
  37         u_char  ether_addr_octet[6];
  38 };
  39 .Ed
  40 .Pp
  41 The
  42 .Fn ether_ntoa
  43 function converts this structure into an ASCII string of the form
  44 ``xx:xx:xx:xx:xx:xx'', consisting of 6 hexadecimal numbers separated
  45 by colons.  It returns a pointer to a static buffer that is reused for
  46 each call.
  47 The
  48 .Fn ether_aton
  49 converts an ASCII string of the same form and to a structure
  50 containing the 6 octets of the address.  It returns a pointer to a
  51 static structure that is reused for each call.
  52 .Pp
  53 The
  54 .Fn ether_ntohost
  55 and
  56 .Fn ether_hostton
  57 functions interrogate the data base mapping host names to Ethernet
  58 addresses,
  59 .Pa /etc/ethers .
  60 The
  61 .Fn ether_ntohost
  62 function looks up the given Ethernet address and writes the associated
  63 host name into the character buffer passed.
  64 The
  65 .Fn ether_hostton
  66 function looks up the given host name and writes the associated
  67 Ethernet address into the structure passed.  Both functions return
  68 zero if they find the requested host name or address, and -1 if not.
  69 Each call reads
  70 .Pa /etc/ethers
  71 from the beginning; if a + appears alone on a line in the file, then
  72 .Fn ether_hostton
  73 will consult the
  74 .Pa ethers.byname
  75 YP map, and
  76 .Fn ether_ntohost
  77 will consult the
  78 .Pa ethers.byaddr
  79 YP map.
  80 .Pp
  81 The
  82 .Fn ether_line
  83 function parses a line from the
  84 .Pa /etc/ethers
  85 file and fills in the passed ``struct ether_addr'' and character
  86 buffer with the Ethernet address and host name on the line.  It
  87 returns zero if the line was successfully parsed and -1 if not.
  88 .Pp
  89 The
  90 .Fa hostname
  91 buffer for
  92 .Fn ether_line
  93 and
  94 .Fn ether_ntohost
  95 should be at least
  96 .Dv MAXHOSTNAMELEN
  97 + 1
  98 characters long, to prevent a buffer overflow during parsing.
  99 .Sh FILES
 100 .Bl -tag -width /etc/ethers -compact
 101 .It Pa /etc/ethers
 102 .El
 103 .Sh SEE ALSO
 104 .Xr ethers 5
 105 .Sh HISTORY
 106 The
 107 .Fn ether_ntoa ,
 108 .Fn ether_aton ,
 109 .Fn ether_ntohost ,
 110 .Fn ether_hostton ,
 111 and
 112 .Fn ether_line
 113 functions were adopted from
 114 .Tn SunOS
 115 and appeared in
 116 .Nx 1.0 .
 117 .Sh BUGS
 118 The data space used by these functions is static; if future use
 119 requires the data, it should be copied before any subsequent calls to
 120 these functions overwrite it.