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.Vt ether_addr 63structure, which is defined in the header file 64.In 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.Fa l , 83an 84.Tn ASCII 85string in 86.Xr ethers 5 87format and sets 88.Fa e 89to the ethernet address specified in the string and 90.Fa 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.Vt ether_addr 102structure. 103Likewise, 104.Fn ether_ntoa 105converts an ethernet address specified as an 106.Vt 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. 119The 120.Fn ether_ntohost 121function 122converts from ethernet address to hostname, and 123.Fn ether_hostton 124converts from hostname to ethernet address. 125.Sh RETURN VALUES 126The 127.Fn ether_line 128function 129returns zero on success and non-zero if it was unable to parse 130any part of the supplied line 131.Fa l . 132It returns the extracted ethernet address in the supplied 133.Vt ether_addr 134structure 135.Fa e 136and the hostname in the supplied string 137.Fa h . 138.Pp 139On success, 140.Fn ether_ntoa 141returns a pointer to a string containing an 142.Tn ASCII 143representation of an ethernet address. 144If it is unable to convert 145the supplied 146.Vt ether_addr 147structure, it returns a 148.Dv NULL 149pointer. 150Likewise, 151.Fn ether_aton 152returns a pointer to an 153.Vt ether_addr 154structure on success and a 155.Dv NULL 156pointer on failure. 157.Pp 158The 159.Fn ether_ntohost 160and 161.Fn ether_hostton 162functions both return zero on success or non-zero if they were 163unable to find a match in the 164.Pa /etc/ethers 165database. 166.Sh NOTES 167The user must insure that the hostname strings passed to the 168.Fn ether_line , 169.Fn ether_ntohost 170and 171.Fn ether_hostton 172functions are large enough to contain the returned hostnames. 173.Sh NIS INTERACTION 174If the 175.Pa /etc/ethers 176contains a line with a single + in it, the 177.Fn ether_ntohost 178and 179.Fn ether_hostton 180functions will attempt to consult the NIS 181.Pa ethers.byname 182and 183.Pa ethers.byaddr 184maps in addition to the data in the 185.Pa /etc/ethers 186file. 187.Sh SEE ALSO 188.Xr ethers 5 , 189.Xr yp 8 190.Sh BUGS 191The 192.Fn ether_aton 193and 194.Fn ether_ntoa 195functions returns values that are stored in static memory areas 196which may be overwritten the next time they are called. 197.Sh HISTORY 198This particular implementation of the 199.Nm 200library functions were written for and first appeared in 201.Fx 2.1 . 202