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