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 .