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 October 30, 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 net/ethernet.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 Likewise,
 170 .Fn ether_aton
 171 and
 172 .Fn ether_aton_r
 173 return a pointer to an
 174 .Vt ether_addr
 175 structure on success and a
 176 .Dv NULL
 177 pointer on failure.
 178 .Fn ether_aton
 179 stores the result in a static buffer;
 180 .Fn ether_aton_r
 181 stores the result in a user-passed buffer.
 182 .Pp
 183 The
 184 .Fn ether_ntohost
 185 and
 186 .Fn ether_hostton
 187 functions both return zero on success or non-zero if they were
 188 unable to find a match in the
 189 .Pa /etc/ethers
 190 database.
 191 .Sh NOTES
 192 The user must ensure that the hostname strings passed to the
 193 .Fn ether_line ,
 194 .Fn ether_ntohost
 195 and
 196 .Fn ether_hostton
 197 functions are large enough to contain the returned hostnames.
 198 .Sh NIS INTERACTION
 199 If the
 200 .Pa /etc/ethers
 201 contains a line with a single + in it, the
 202 .Fn ether_ntohost
 203 and
 204 .Fn ether_hostton
 205 functions will attempt to consult the NIS
 206 .Pa ethers.byname
 207 and
 208 .Pa ethers.byaddr
 209 maps in addition to the data in the
 210 .Pa /etc/ethers
 211 file.
 212 .Sh SEE ALSO
 213 .Xr ethers 5 ,
 214 .Xr yp 8
 215 .Sh HISTORY
 216 This particular implementation of the
 217 .Nm
 218 library functions were written for and first appeared in
 219 .Fx 2.1 .
 220 Thread-safe function variants first appeared in
 221 .Fx 7.0 .
 222 .Sh BUGS
 223 The
 224 .Fn ether_aton
 225 and
 226 .Fn ether_ntoa
 227 functions returns values that are stored in static memory areas
 228 which may be overwritten the next time they are called.
 229 .Pp
 230 .Fn ether_ntoa_r
 231 accepts a character buffer pointer, but not a buffer length.
 232 The caller must ensure adequate space is available in the buffer in order to
 233 avoid a buffer overflow.