lib/libc/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.10.2.11 2002/02/01 15:51:17 ru Exp $
  32 .\" $DragonFly: src/lib/libc/net/ethers.3,v 1.4 2006/05/26 19:39:37 swildner Exp $
  33 .\"
  34 .Dd April 12, 1995
  35 .Dt ETHERS 3
  36 .Os
  37 .Sh NAME
  38 .Nm ethers ,
  39 .Nm ether_line ,
  40 .Nm ether_aton ,
  41 .Nm ether_ntoa ,
  42 .Nm ether_ntohost ,
  43 .Nm ether_hostton
  44 .Nd Ethernet address conversion and lookup routines
  45 .Sh LIBRARY
  46 .Lb libc
  47 .Sh SYNOPSIS
  48 .In sys/types.h
  49 .In sys/socket.h
  50 .In net/ethernet.h
  51 .Ft int
  52 .Fn ether_line "const char *l" "struct ether_addr *e" "char *hostname"
  53 .Ft struct ether_addr *
  54 .Fn ether_aton "const char *a"
  55 .Ft char *
  56 .Fn ether_ntoa "const struct ether_addr *n"
  57 .Ft int
  58 .Fn ether_ntohost "char *hostname" "const struct ether_addr *e"
  59 .Ft int
  60 .Fn ether_hostton "const char *hostname" "struct ether_addr *e"
  61 .Sh DESCRIPTION
  62 These functions operate on ethernet addresses using an
  63 .Ar ether_addr
  64 structure, which is defined in the header file
  65 .In netinet/if_ether.h :
  66 .Bd -literal -offset indent
  67 /*
  68  * The number of bytes in an ethernet (MAC) address.
  69  */
  70 #define ETHER_ADDR_LEN          6
  71
  72 /*
  73  * Structure of a 48-bit Ethernet address.
  74  */
  75 struct  ether_addr {
  76         u_char octet[ETHER_ADDR_LEN];
  77 };
  78 .Ed
  79 .Pp
  80 The function
  81 .Fn ether_line
  82 scans
  83 .Ar l ,
  84 an
  85 .Tn ASCII
  86 string in
  87 .Xr ethers 5
  88 format and sets
  89 .Ar e
  90 to the ethernet address specified in the string and
  91 .Ar h
  92 to the hostname.
  93 This function is used to parse lines from
  94 .Pa /etc/ethers
  95 into their component parts.
  96 .Pp
  97 The
  98 .Fn ether_aton
  99 function converts an
 100 .Tn ASCII
 101 representation of an ethernet address into an
 102 .Ar ether_addr
 103 structure.
 104 Likewise,
 105 .Fn ether_ntoa
 106 converts an ethernet address specified as an
 107 .Ar ether_addr
 108 structure into an
 109 .Tn ASCII
 110 string.
 111 .Pp
 112 The
 113 .Fn ether_ntohost
 114 and
 115 .Fn ether_hostton
 116 functions map ethernet addresses to their corresponding hostnames
 117 as specified in the
 118 .Pa /etc/ethers
 119 database.
 120 .Fn ether_ntohost
 121 converts from ethernet address to hostname, and
 122 .Fn ether_hostton
 123 converts from hostname to ethernet address.
 124 .Sh RETURN VALUES
 125 .Fn ether_line
 126 returns zero on success and non-zero if it was unable to parse
 127 any part of the supplied line
 128 .Ar l .
 129 It returns the extracted ethernet address in the supplied
 130 .Ar ether_addr
 131 structure
 132 .Ar e
 133 and the hostname in the supplied string
 134 .Ar h .
 135 .Pp
 136 On success,
 137 .Fn ether_ntoa
 138 returns a pointer to a string containing an
 139 .Tn ASCII
 140 representation of an ethernet address.
 141 If it is unable to convert
 142 the supplied
 143 .Ar ether_addr
 144 structure, it returns a
 145 .Dv NULL
 146 pointer.
 147 Likewise,
 148 .Fn ether_aton
 149 returns a pointer to an
 150 .Ar ether_addr
 151 structure on success and a
 152 .Dv NULL
 153 pointer on failure.
 154 .Pp
 155 The
 156 .Fn ether_ntohost
 157 and
 158 .Fn ether_hostton
 159 functions both return zero on success or non-zero if they were
 160 unable to find a match in the
 161 .Pa /etc/ethers
 162 database.
 163 .Sh NOTES
 164 The user must insure that the hostname strings passed to the
 165 .Fn ether_line ,
 166 .Fn ether_ntohost
 167 and
 168 .Fn ether_hostton
 169 functions are large enough to contain the returned hostnames.
 170 .Sh NIS INTERACTION
 171 If the
 172 .Pa /etc/ethers
 173 contains a line with a single + in it, the
 174 .Fn ether_ntohost
 175 and
 176 .Fn ether_hostton
 177 functions will attempt to consult the NIS
 178 .Pa ethers.byname
 179 and
 180 .Pa ethers.byaddr
 181 maps in addition to the data in the
 182 .Pa /etc/ethers
 183 file.
 184 .Sh SEE ALSO
 185 .Xr ethers 5 ,
 186 .Xr yp 8
 187 .Sh HISTORY
 188 This particular implementation of the
 189 .Nm
 190 library functions were written for and first appeared in
 191 .Fx 2.1 .
 192 .Sh BUGS
 193 The
 194 .Fn ether_aton
 195 and
 196 .Fn ether_ntoa
 197 functions returns values that are stored in static memory areas
 198 which may be overwritten the next time they are called.