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 68These functions operate on ethernet addresses using an 69.Vt ether_addr 70structure, which is defined in the header file 71.In netinet/if_ether.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 */ 81struct ether_addr { 82 u_char octet[ETHER_ADDR_LEN]; 83}; 84.Ed 85.Pp 86The function 87.Fn ether_line 88scans 89.Fa l , 90an 91.Tn ASCII 92string in 93.Xr ethers 5 94format and sets 95.Fa e 96to the ethernet address specified in the string and 97.Fa h 98to the hostname. 99This function is used to parse lines from 100.Pa /etc/ethers 101into their component parts. 102.Pp 103The 104.Fn ether_aton 105and 106.Fn ether_aton_r 107functions convert 108.Tn ASCII 109representation of ethernet addresses into 110.Vt ether_addr 111structures. 112Likewise, the 113.Fn ether_ntoa 114and 115.Fn ether_ntoa_r 116functions 117convert ethernet addresses specified as 118.Vt ether_addr 119structures into 120.Tn ASCII 121strings. 122.Pp 123The 124.Fn ether_ntohost 125and 126.Fn ether_hostton 127functions map ethernet addresses to their corresponding hostnames 128as specified in the 129.Pa /etc/ethers 130database. 131The 132.Fn ether_ntohost 133function 134converts from ethernet address to hostname, and 135.Fn ether_hostton 136converts from hostname to ethernet address. 137.Sh RETURN VALUES 138The 139.Fn ether_line 140function 141returns zero on success and non-zero if it was unable to parse 142any part of the supplied line 143.Fa l . 144It returns the extracted ethernet address in the supplied 145.Vt ether_addr 146structure 147.Fa e 148and the hostname in the supplied string 149.Fa h . 150.Pp 151On success, 152.Fn ether_ntoa 153and 154.Fn ether_ntoa_r 155functions return a pointer to a string containing an 156.Tn ASCII 157representation of an ethernet address. 158If it is unable to convert 159the supplied 160.Vt ether_addr 161structure, it returns a 162.Dv NULL 163pointer. 164.Fn ether_ntoa 165stores the result in a static buffer; 166.Fn ether_ntoa_r 167stores the result in a user-passed buffer. 168.Pp 169Likewise, 170.Fn ether_aton 171and 172.Fn ether_aton_r 173return a pointer to an 174.Vt ether_addr 175structure on success and a 176.Dv NULL 177pointer on failure. 178.Fn ether_aton 179stores the result in a static buffer; 180.Fn ether_aton_r 181stores the result in a user-passed buffer. 182.Pp 183The 184.Fn ether_ntohost 185and 186.Fn ether_hostton 187functions both return zero on success or non-zero if they were 188unable to find a match in the 189.Pa /etc/ethers 190database. 191.Sh NOTES 192The user must ensure that the hostname strings passed to the 193.Fn ether_line , 194.Fn ether_ntohost 195and 196.Fn ether_hostton 197functions are large enough to contain the returned hostnames. 198.Sh NIS INTERACTION 199If the 200.Pa /etc/ethers 201contains a line with a single + in it, the 202.Fn ether_ntohost 203and 204.Fn ether_hostton 205functions will attempt to consult the NIS 206.Pa ethers.byname 207and 208.Pa ethers.byaddr 209maps in addition to the data in the 210.Pa /etc/ethers 211file. 212.Sh SEE ALSO 213.Xr ethers 5 , 214.Xr yp 8 215.Sh HISTORY 216This particular implementation of the 217.Nm 218library functions were written for and first appeared in 219.Fx 2.1 . 220Thread-safe function variants first appeared in 221.Fx 7.0 . 222.Sh BUGS 223The 224.Fn ether_aton 225and 226.Fn ether_ntoa 227functions returns values that are stored in static memory areas 228which may be overwritten the next time they are called. 229.Pp 230.Fn ether_ntoa_r 231accepts a character buffer pointer, but not a buffer length. 232The caller must ensure adequate space is available in the buffer in order to 233avoid a buffer overflow. 234