1 .\" Copyright (c) 1995 Bill Paul <wpaul@ctr.columbia.edu>.
2 .\" Copyright (c) 2007 Robert N. M. Watson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. All advertising materials mentioning features or use of this software
14 .\" must display the following acknowledgement:
15 .\" This product includes software developed by Bill Paul.
16 .\" 4. Neither the name of the author nor the names of any co-contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" $FreeBSD: src/lib/libc/net/ethers.3,v 1.25 2007/10/30 15:31:41 keramida Exp $
33 .\" $DragonFly: src/lib/libc/net/ethers.3,v 1.4 2006/05/26 19:39:37 swildner Exp $
47 .Nd Ethernet address conversion and lookup routines
55 .Fn ether_line "const char *l" "struct ether_addr *e" "char *hostname"
56 .Ft struct ether_addr *
57 .Fn ether_aton "const char *a"
58 .Ft struct ether_addr *
59 .Fn ether_aton_r "const char *a" "struct ether_addr *e"
61 .Fn ether_ntoa "const struct ether_addr *n"
63 .Fn ether_ntoa_r "const struct ether_addr *n" "char *buf"
65 .Fn ether_ntohost "char *hostname" "const struct ether_addr *e"
67 .Fn ether_hostton "const char *hostname" "struct ether_addr *e"
69 These functions operate on ethernet addresses using an
71 structure, which is defined in the header file
72 .In netinet/if_ether.h :
73 .Bd -literal -offset indent
75 * The number of bytes in an ethernet (MAC) address.
77 #define ETHER_ADDR_LEN 6
80 * Structure of a 48-bit Ethernet address.
83 u_char octet[ETHER_ADDR_LEN];
97 to the ethernet address specified in the string and
100 This function is used to parse lines from
102 into their component parts.
110 representation of ethernet addresses into
118 convert ethernet addresses specified as
128 functions map ethernet addresses to their corresponding hostnames
135 converts from ethernet address to hostname, and
137 converts from hostname to ethernet address.
142 returns zero on success and non-zero if it was unable to parse
143 any part of the supplied line
145 It returns the extracted ethernet address in the supplied
149 and the hostname in the supplied string
156 functions return a pointer to a string containing an
158 representation of an ethernet address.
159 If it is unable to convert
162 structure, it returns a
166 stores the result in a static buffer;
168 stores the result in a user-passed buffer.
174 return a pointer to an
176 structure on success and a
180 stores the result in a static buffer;
182 stores the result in a user-passed buffer.
188 functions both return zero on success or non-zero if they were
189 unable to find a match in the
193 The user must insure that the hostname strings passed to the
198 functions are large enough to contain the returned hostnames.
202 contains a line with a single + in it, the
206 functions will attempt to consult the NIS
210 maps in addition to the data in the
217 This particular implementation of the
219 library functions were written for and first appeared in
221 Thread-safe function variants first appeared in
228 functions returns values that are stored in static memory areas
229 which may be overwritten the next time they are called.
232 accepts a character buffer pointer, but not a buffer length.
233 The caller must ensure adequate space is available in the buffer in order to
234 avoid a buffer overflow.