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