net/ethers.3

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