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