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 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.
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
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
137representation of an ethernet address.
138If it is unable to convert
139the supplied
140.Ar ether_addr
141structure, it returns a
142.Dv NULL
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 .
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 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.
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
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
137representation of an ethernet address.
138If it is unable to convert
139the supplied
140.Ar ether_addr
141structure, it returns a
142.Dv NULL
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 .