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.\" $Id: ethers.3,v 1.7 1997/02/22 15:00:05 peter Exp $ 32.\" 33.Dd April 12, 1995 34.Dt ETHERS 3 35.Os FreeBSD 2.1 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 SYNOPSIS 45.Fd #include <sys/types.h> 46.Fd #include <sys/socket.h> 47.Fd #include <net/ethernet.h> 48.Ft int 49.Fn ether_line "char *l" "struct ether_addr *e" "char *hostname" 50.Ft struct ether_addr * 51.Fn ether_aton "char *a" 52.Ft char * 53.Fn ether_ntoa "struct ether_addr *n" 54.Ft int 55.Fn ether_ntohost "char *hostname" "struct ether_addr *e" 56.Ft int 57.Fn ether_hostton "char *hostname" "struct ether_addr *e" 58.Sh DESCRIPTION 59These functions operate on ethernet addresses using an 60.Ar ether_addr 61structure, which is defined in the header file 62.Aq Pa netinet/if_ether.h : 63.Bd -literal -offset indent 64/* 65 * The number of bytes in an ethernet (MAC) address. 66 */ 67#define ETHER_ADDR_LEN 6 68 69/* 70 * Structure of a 48-bit Ethernet address. 71 */ 72struct ether_addr { 73 u_char octet[ETHER_ADDR_LEN]; 74}; 75.Ed 76.Pp 77The function 78.Fn ether_line 79scans 80.Ar l , 81an 82.Tn ASCII 83string in 84.Xr ethers 5 85format and sets 86.Ar e 87to the ethernet address specified in the string and 88.Ar h 89to the hostname. This function is used to parse lines from 90.Pa /etc/ethers 91into their component parts. 92.Pp 93The 94.Fn ether_aton 95function converts an 96.Tn ASCII 97representation of an ethernet address into an 98.Ar ether_addr 99structure. Likewise, 100.Fn ether_ntoa 101converts an ethernet address specified as an 102.Ar ether_addr 103structure into an 104.Tn ASCII 105string. 106.Pp 107The 108.Fn ether_ntohost 109and 110.Fn ether_hostton 111functions map ethernet addresses to their corresponding hostnames 112as specified in the 113.Pa /etc/ethers 114database. 115.Fn ether_ntohost 116converts from ethernet address to hostname, and 117.Fn ether_hostton 118converts from hostname to ethernet address. 119.Sh RETURN VALUES 120.Fn ether_line 121returns zero on success and non-zero if it was unable to parse 122any part of the supplied line 123.Ar l . 124It returns the extracted ethernet address in the supplied 125.Ar ether_addr 126structure 127.Ar e 128and the hostname in the supplied string 129.Ar h . 130.Pp 131On success, 132.Fn ether_ntoa 133returns a pointer to a string containing an 134.Tn ASCII 135representation of an ethernet address. If it is unable to convert 136the supplied 137.Ar ether_addr 138structure, it returns a 139.Dv NULL 140pointer. Likewise, 141.Fn ether_aton 142returns a pointer to an 143.Ar ether_addr 144structure on success and a 145.Dv NULL 146pointer on failure. 147.Pp 148The 149.Fn ether_ntohost 150and 151.Fn ether_hostton 152functions both return zero on success or non-zero if they were 153unable to find a match in the 154.Pa /etc/ethers 155database. 156.Sh NOTES 157The user must insure that the hostname strings passed to the 158.Fn ether_line , 159.Fn ether_ntohost 160and 161.Fn ether_hostton 162functions are large enough to contain the returned hostnames. 163.Sh NIS INTERACTION 164If the 165.Pa /etc/ethers 166contains a line with a single + in it, the 167.Fn ether_ntohost 168and 169.Fn ether_hostton 170functions will attempt to consult the NIS 171.Pa ethers.byname 172and 173.Pa ethers.byaddr 174maps in addition to the data in the 175.Pa /etc/ethers 176file. 177.Sh SEE ALSO 178.Xr yp 4 , 179.Xr ethers 5 180.Sh BUGS 181.Pp 182The 183.Fn ether_aton 184and 185.Fn ether_ntoa 186functions returns values that are stored in static memory areas 187which may be overwritten the next time they are called. 188.Sh HISTORY 189This particular implementation of the 190.Nm ethers 191library functions were written for and first appeared in 192.Fx 2.1 . 193