lib/libc/net/ethers.3

   1 .\" Copyright (c) 1995 Bill Paul <wpaul@ctr.columbia.edu>.
   2 .\" Copyright (c) 2007 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by Bill Paul.
  16 .\" 4. Neither the name of the author nor the names of any co-contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd May 13, 2007
  35 .Dt ETHERS 3
  36 .Os
  37 .Sh NAME
  38 .Nm ethers ,
  39 .Nm ether_line ,
  40 .Nm ether_aton ,
  41 .Nm ether_aton_r ,
  42 .Nm ether_ntoa ,
  43 .Nm ether_ntoa_r ,
  44 .Nm ether_ntohost ,
  45 .Nm ether_hostton
  46 .Nd Ethernet address conversion and lookup routines
  47 .Sh LIBRARY
  48 .Lb libc
  49 .Sh SYNOPSIS
  50 .In sys/types.h
  51 .In sys/socket.h
  52 .In net/ethernet.h
  53 .Ft int
  54 .Fn ether_line "const char *l" "struct ether_addr *e" "char *hostname"
  55 .Ft struct ether_addr *
  56 .Fn ether_aton "const char *a"
  57 .Ft struct ether_addr *
  58 .Fn ether_aton_r "const char *a" "struct ether_addr *e"
  59 .Ft char *
  60 .Fn ether_ntoa "const struct ether_addr *n"
  61 .Ft char *
  62 .Fn ether_ntoa_r "const struct ether_addr *n" "char *buf"
  63 .Ft int
  64 .Fn ether_ntohost "char *hostname" "const struct ether_addr *e"
  65 .Ft int
  66 .Fn ether_hostton "const char *hostname" "struct ether_addr *e"
  67 .Sh DESCRIPTION
  68 These functions operate on ethernet addresses using an
  69 .Vt ether_addr
  70 structure, which is defined in the header file
  71 .In netinet/if_ether.h :
  72 .Bd -literal -offset indent
  73 /*
  74  * The number of bytes in an ethernet (MAC) address.
  75  */
  76 #define ETHER_ADDR_LEN          6
  77
  78 /*
  79  * Structure of a 48-bit Ethernet address.
  80  */
  81 struct  ether_addr {
  82         u_char octet[ETHER_ADDR_LEN];
  83 };
  84 .Ed
  85 .Pp
  86 The function
  87 .Fn ether_line
  88 scans
  89 .Fa l ,
  90 an
  91 .Tn ASCII
  92 string in
  93 .Xr ethers 5
  94 format and sets
  95 .Fa e
  96 to the ethernet address specified in the string and
  97 .Fa h
  98 to the hostname.
  99 This function is used to parse lines from
 100 .Pa /etc/ethers
 101 into their component parts.
 102 .Pp
 103 The
 104 .Fn ether_aton
 105 and
 106 .Fn ether_aton_r
 107 functions convert
 108 .Tn ASCII
 109 representation of ethernet addresses into
 110 .Vt ether_addr
 111 structures.
 112 Likewise, the
 113 .Fn ether_ntoa
 114 and
 115 .Fn ether_ntoa_r
 116 functions
 117 convert ethernet addresses specified as
 118 .Vt ether_addr
 119 structures into
 120 .Tn ASCII
 121 strings.
 122 .Pp
 123 The
 124 .Fn ether_ntohost
 125 and
 126 .Fn ether_hostton
 127 functions map ethernet addresses to their corresponding hostnames
 128 as specified in the
 129 .Pa /etc/ethers
 130 database.
 131 The
 132 .Fn ether_ntohost
 133 function
 134 converts from ethernet address to hostname, and
 135 .Fn ether_hostton
 136 converts from hostname to ethernet address.
 137 .Sh RETURN VALUES
 138 The
 139 .Fn ether_line
 140 function
 141 returns zero on success and non-zero if it was unable to parse
 142 any part of the supplied line
 143 .Fa l .
 144 It returns the extracted ethernet address in the supplied
 145 .Vt ether_addr
 146 structure
 147 .Fa e
 148 and the hostname in the supplied string
 149 .Fa h .
 150 .Pp
 151 On success,
 152 .Fn ether_ntoa
 153 and
 154 .Fn ether_ntoa_r
 155 functions return a pointer to a string containing an
 156 .Tn ASCII
 157 representation of an ethernet address.
 158 If it is unable to convert
 159 the supplied
 160 .Vt ether_addr
 161 structure, it returns a
 162 .Dv NULL
 163 pointer.
 164 .Fn ether_ntoa
 165 stores the result in a static buffer;
 166 .Fn ether_ntoa_r
 167 stores the result in a user-passed buffer.
 168 .Pp
 169
 170 Likewise,
 171 .Fn ether_aton
 172 and
 173 .Fn ether_aton_r
 174 return a pointer to an
 175 .Vt ether_addr
 176 structure on success and a
 177 .Dv NULL
 178 pointer on failure.
 179 .Fn ether_aton
 180 stores the result in a static buffer;
 181 .Fn ether_aton_r
 182 stores the result in a user-passed buffer.
 183 .Pp
 184 The
 185 .Fn ether_ntohost
 186 and
 187 .Fn ether_hostton
 188 functions both return zero on success or non-zero if they were
 189 unable to find a match in the
 190 .Pa /etc/ethers
 191 database.
 192 .Sh NOTES
 193 The user must insure that the hostname strings passed to the
 194 .Fn ether_line ,
 195 .Fn ether_ntohost
 196 and
 197 .Fn ether_hostton
 198 functions are large enough to contain the returned hostnames.
 199 .Sh NIS INTERACTION
 200 If the
 201 .Pa /etc/ethers
 202 contains a line with a single + in it, the
 203 .Fn ether_ntohost
 204 and
 205 .Fn ether_hostton
 206 functions will attempt to consult the NIS
 207 .Pa ethers.byname
 208 and
 209 .Pa ethers.byaddr
 210 maps in addition to the data in the
 211 .Pa /etc/ethers
 212 file.
 213 .Sh SEE ALSO
 214 .Xr ethers 5 ,
 215 .Xr yp 8
 216 .Sh HISTORY
 217 This particular implementation of the
 218 .Nm
 219 library functions were written for and first appeared in
 220 .Fx 2.1 .
 221 Thread-safe function variants first appeared in
 222 .Fx 7.0 .
 223 .Sh BUGS
 224 The
 225 .Fn ether_aton
 226 and
 227 .Fn ether_ntoa
 228 functions returns values that are stored in static memory areas
 229 which may be overwritten the next time they are called.
 230 .Pp
 231 .Fn ether_ntoa_r
 232 accepts a character buffer pointer, but not a buffer length.
 233 The caller must ensure adequate space is available in the buffer in order to
 234 avoid a buffer overflow.