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 May 13, 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 169 170Likewise, 171.Fn ether_aton 172and 173.Fn ether_aton_r 174return a pointer to an 175.Vt ether_addr 176structure on success and a 177.Dv NULL 178pointer on failure. 179.Fn ether_aton 180stores the result in a static buffer; 181.Fn ether_aton_r 182stores the result in a user-passed buffer. 183.Pp 184The 185.Fn ether_ntohost 186and 187.Fn ether_hostton 188functions both return zero on success or non-zero if they were 189unable to find a match in the 190.Pa /etc/ethers 191database. 192.Sh NOTES 193The user must insure that the hostname strings passed to the 194.Fn ether_line , 195.Fn ether_ntohost 196and 197.Fn ether_hostton 198functions are large enough to contain the returned hostnames. 199.Sh NIS INTERACTION 200If the 201.Pa /etc/ethers 202contains a line with a single + in it, the 203.Fn ether_ntohost 204and 205.Fn ether_hostton 206functions will attempt to consult the NIS 207.Pa ethers.byname 208and 209.Pa ethers.byaddr 210maps in addition to the data in the 211.Pa /etc/ethers 212file. 213.Sh SEE ALSO 214.Xr ethers 5 , 215.Xr yp 8 216.Sh HISTORY 217This particular implementation of the 218.Nm 219library functions were written for and first appeared in 220.Fx 2.1 . 221Thread-safe function variants first appeared in 222.Fx 7.0 . 223.Sh BUGS 224The 225.Fn ether_aton 226and 227.Fn ether_ntoa 228functions returns values that are stored in static memory areas 229which may be overwritten the next time they are called. 230.Pp 231.Fn ether_ntoa_r 232accepts a character buffer pointer, but not a buffer length. 233The caller must ensure adequate space is available in the buffer in order to 234avoid a buffer overflow. 235