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: head/lib/libc/net/ethers.3 50476 1999-08-28 00:22:10Z peter $
|
31.\" $FreeBSD: head/lib/libc/net/ethers.3 57686 2000-03-02 09:14:21Z sheldonh $ |
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
|
89to the hostname. 90This function is used to parse lines from |
91.Pa /etc/ethers 92into their component parts. 93.Pp 94The 95.Fn ether_aton 96function converts an 97.Tn ASCII 98representation of an ethernet address into an 99.Ar ether_addr
|
99structure. Likewise,
|
100structure. 101Likewise, |
102.Fn ether_ntoa 103converts an ethernet address specified as an 104.Ar ether_addr 105structure into an 106.Tn ASCII 107string. 108.Pp 109The 110.Fn ether_ntohost 111and 112.Fn ether_hostton 113functions map ethernet addresses to their corresponding hostnames 114as specified in the 115.Pa /etc/ethers 116database. 117.Fn ether_ntohost 118converts from ethernet address to hostname, and 119.Fn ether_hostton 120converts from hostname to ethernet address. 121.Sh RETURN VALUES 122.Fn ether_line 123returns zero on success and non-zero if it was unable to parse 124any part of the supplied line 125.Ar l . 126It returns the extracted ethernet address in the supplied 127.Ar ether_addr 128structure 129.Ar e 130and the hostname in the supplied string 131.Ar h . 132.Pp 133On success, 134.Fn ether_ntoa 135returns a pointer to a string containing an 136.Tn ASCII
|
135representation of an ethernet address. If it is unable to convert
|
137representation of an ethernet address. 138If it is unable to convert |
139the supplied 140.Ar ether_addr 141structure, it returns a 142.Dv NULL
|
140pointer. Likewise,
|
143pointer. 144Likewise, |
145.Fn ether_aton 146returns a pointer to an 147.Ar ether_addr 148structure on success and a 149.Dv NULL 150pointer on failure. 151.Pp 152The 153.Fn ether_ntohost 154and 155.Fn ether_hostton 156functions both return zero on success or non-zero if they were 157unable to find a match in the 158.Pa /etc/ethers 159database. 160.Sh NOTES 161The user must insure that the hostname strings passed to the 162.Fn ether_line , 163.Fn ether_ntohost 164and 165.Fn ether_hostton 166functions are large enough to contain the returned hostnames. 167.Sh NIS INTERACTION 168If the 169.Pa /etc/ethers 170contains a line with a single + in it, the 171.Fn ether_ntohost 172and 173.Fn ether_hostton 174functions will attempt to consult the NIS 175.Pa ethers.byname 176and 177.Pa ethers.byaddr 178maps in addition to the data in the 179.Pa /etc/ethers 180file. 181.Sh SEE ALSO 182.Xr yp 4 , 183.Xr ethers 5 184.Sh BUGS 185.Pp 186The 187.Fn ether_aton 188and 189.Fn ether_ntoa 190functions returns values that are stored in static memory areas 191which may be overwritten the next time they are called. 192.Sh HISTORY 193This particular implementation of the 194.Nm ethers 195library functions were written for and first appeared in 196.Fx 2.1 .
|