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: src/lib/libc/net/ethers.3,v 1.25 2007/10/30 15:31:41 keramida Exp $
  33 .\" $DragonFly: src/lib/libc/net/ethers.3,v 1.4 2006/05/26 19:39:37 swildner Exp $
  34 .\"
  35 .Dd October 30, 2007
  36 .Dt ETHERS 3
  37 .Os
  38 .Sh NAME
  39 .Nm ethers ,
  40 .Nm ether_line ,
  41 .Nm ether_aton ,
  42 .Nm ether_aton_r ,
  43 .Nm ether_ntoa ,
  44 .Nm ether_ntoa_r ,
  45 .Nm ether_ntohost ,
  46 .Nm ether_hostton
  47 .Nd Ethernet address conversion and lookup routines
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In sys/types.h
  52 .In sys/socket.h
  53 .In net/ethernet.h
  54 .Ft int
  55 .Fn ether_line "const char *l" "struct ether_addr *e" "char *hostname"
  56 .Ft struct ether_addr *
  57 .Fn ether_aton "const char *a"
  58 .Ft struct ether_addr *
  59 .Fn ether_aton_r "const char *a" "struct ether_addr *e"
  60 .Ft char *
  61 .Fn ether_ntoa "const struct ether_addr *n"
  62 .Ft char *
  63 .Fn ether_ntoa_r "const struct ether_addr *n" "char *buf"
  64 .Ft int
  65 .Fn ether_ntohost "char *hostname" "const struct ether_addr *e"
  66 .Ft int
  67 .Fn ether_hostton "const char *hostname" "struct ether_addr *e"
  68 .Sh DESCRIPTION
  69 These functions operate on ethernet addresses using an
  70 .Vt ether_addr
  71 structure, which is defined in the header file
  72 .In netinet/if_ether.h :
  73 .Bd -literal -offset indent
  74 /*
  75  * The number of bytes in an ethernet (MAC) address.
  76  */
  77 #define ETHER_ADDR_LEN          6
  78
  79 /*
  80  * Structure of a 48-bit Ethernet address.
  81  */
  82 struct  ether_addr {
  83         u_char octet[ETHER_ADDR_LEN];
  84 };
  85 .Ed
  86 .Pp
  87 The function
  88 .Fn ether_line
  89 scans
  90 .Fa l ,
  91 an
  92 .Tn ASCII
  93 string in
  94 .Xr ethers 5
  95 format and sets
  96 .Fa e
  97 to the ethernet address specified in the string and
  98 .Fa h
  99 to the hostname.
 100 This function is used to parse lines from
 101 .Pa /etc/ethers
 102 into their component parts.
 103 .Pp
 104 The
 105 .Fn ether_aton
 106 and
 107 .Fn ether_aton_r
 108 functions convert
 109 .Tn ASCII
 110 representation of ethernet addresses into
 111 .Vt ether_addr
 112 structures.
 113 Likewise, the
 114 .Fn ether_ntoa
 115 and
 116 .Fn ether_ntoa_r
 117 functions
 118 convert ethernet addresses specified as
 119 .Vt ether_addr
 120 structures into
 121 .Tn ASCII
 122 strings.
 123 .Pp
 124 The
 125 .Fn ether_ntohost
 126 and
 127 .Fn ether_hostton
 128 functions map ethernet addresses to their corresponding hostnames
 129 as specified in the
 130 .Pa /etc/ethers
 131 database.
 132 The
 133 .Fn ether_ntohost
 134 function
 135 converts from ethernet address to hostname, and
 136 .Fn ether_hostton
 137 converts from hostname to ethernet address.
 138 .Sh RETURN VALUES
 139 The
 140 .Fn ether_line
 141 function
 142 returns zero on success and non-zero if it was unable to parse
 143 any part of the supplied line
 144 .Fa l .
 145 It returns the extracted ethernet address in the supplied
 146 .Vt ether_addr
 147 structure
 148 .Fa e
 149 and the hostname in the supplied string
 150 .Fa h .
 151 .Pp
 152 On success,
 153 .Fn ether_ntoa
 154 and
 155 .Fn ether_ntoa_r
 156 functions return a pointer to a string containing an
 157 .Tn ASCII
 158 representation of an ethernet address.
 159 If it is unable to convert
 160 the supplied
 161 .Vt ether_addr
 162 structure, it returns a
 163 .Dv NULL
 164 pointer.
 165 .Fn ether_ntoa
 166 stores the result in a static buffer;
 167 .Fn ether_ntoa_r
 168 stores the result in a user-passed buffer.
 169 .Pp
 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.