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$ 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 61These functions operate on ethernet addresses using an 62.Ar ether_addr 63structure, 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 */ 74struct ether_addr { 75 u_char octet[ETHER_ADDR_LEN]; 76}; 77.Ed 78.Pp 79The function 80.Fn ether_line 81scans 82.Ar l , 83an 84.Tn ASCII 85string in 86.Xr ethers 5 87format and sets 88.Ar e 89to the ethernet address specified in the string and 90.Ar h 91to the hostname. 92This function is used to parse lines from 93.Pa /etc/ethers 94into their component parts. 95.Pp 96The 97.Fn ether_aton 98function converts an 99.Tn ASCII 100representation of an ethernet address into an 101.Ar ether_addr 102structure. 103Likewise, 104.Fn ether_ntoa 105converts an ethernet address specified as an 106.Ar ether_addr 107structure into an 108.Tn ASCII 109string. 110.Pp 111The 112.Fn ether_ntohost 113and 114.Fn ether_hostton 115functions map ethernet addresses to their corresponding hostnames 116as specified in the 117.Pa /etc/ethers 118database. 119.Fn ether_ntohost 120converts from ethernet address to hostname, and 121.Fn ether_hostton 122converts from hostname to ethernet address. 123.Sh RETURN VALUES 124.Fn ether_line 125returns zero on success and non-zero if it was unable to parse 126any part of the supplied line 127.Ar l . 128It returns the extracted ethernet address in the supplied 129.Ar ether_addr 130structure 131.Ar e 132and the hostname in the supplied string 133.Ar h . 134.Pp 135On success, 136.Fn ether_ntoa 137returns a pointer to a string containing an 138.Tn ASCII 139representation of an ethernet address. 140If it is unable to convert 141the supplied 142.Ar ether_addr 143structure, it returns a 144.Dv NULL 145pointer. 146Likewise, 147.Fn ether_aton 148returns a pointer to an 149.Ar ether_addr 150structure on success and a 151.Dv NULL 152pointer on failure. 153.Pp 154The 155.Fn ether_ntohost 156and 157.Fn ether_hostton 158functions both return zero on success or non-zero if they were 159unable to find a match in the 160.Pa /etc/ethers 161database. 162.Sh NOTES 163The user must insure that the hostname strings passed to the 164.Fn ether_line , 165.Fn ether_ntohost 166and 167.Fn ether_hostton 168functions are large enough to contain the returned hostnames. 169.Sh NIS INTERACTION 170If the 171.Pa /etc/ethers 172contains a line with a single + in it, the 173.Fn ether_ntohost 174and 175.Fn ether_hostton 176functions will attempt to consult the NIS 177.Pa ethers.byname 178and 179.Pa ethers.byaddr 180maps in addition to the data in the 181.Pa /etc/ethers 182file. 183.Sh SEE ALSO 184.Xr ethers 5 , 185.Xr yp 8 186.Sh BUGS 187The 188.Fn ether_aton 189and 190.Fn ether_ntoa 191functions returns values that are stored in static memory areas 192which may be overwritten the next time they are called. 193.Sh HISTORY 194This particular implementation of the 195.Nm 196library functions were written for and first appeared in 197.Fx 2.1 . 198