| blob | 4d8db4a40b22e2897e2e38c7f62f157fd3c55826 |
1 .\" Copyright 2004 The Aerospace Corporation. All rights reserved.
2 .\"
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions
5 .\" are met:
6 .\"
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. The name of The Aerospace Corporation may not be used to endorse or
13 .\" promote products derived from this software.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE AEROSPACE CORPORATION "AS IS" AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AEROSPACE CORPORATION BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" SUCH DAMAGE.
26 .\"
27 .\" Copyright (c) 1995
28 .\" Bill Paul <wpaul@ctr.columbia.edu>. All rights reserved.
29 .\"
30 .\" Redistribution and use in source and binary forms, with or without
31 .\" modification, are permitted provided that the following conditions
32 .\" are met:
33 .\" 1. Redistributions of source code must retain the above copyright
34 .\" notice, this list of conditions and the following disclaimer.
35 .\" 2. Redistributions in binary form must reproduce the above copyright
36 .\" notice, this list of conditions and the following disclaimer in the
37 .\" documentation and/or other materials provided with the distribution.
38 .\" 3. All advertising materials mentioning features or use of this software
39 .\" must display the following acknowledgement:
40 .\" This product includes software developed by Bill Paul.
41 .\" 4. Neither the name of the author nor the names of any co-contributors
42 .\" may be used to endorse or promote products derived from this software
43 .\" without specific prior written permission.
44 .\"
45 .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND
46 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
47 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
48 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
49 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
50 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
51 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
52 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
53 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
54 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
55 .\" SUCH DAMAGE.
56 .\"
57 .\" $FreeBSD: src/lib/libc/net/eui64.3,v 1.4 2005/01/20 09:17:03 ru Exp $
58 .\" $DragonFly: src/lib/libc/net/eui64.3,v 1.4 2006/05/26 19:39:37 swildner Exp $
59 .\"
60 .Dd March 4, 2004
61 .Dt EUI64 3
62 .Os
63 .Sh NAME
64 .Nm eui64 ,
65 .\" .Nm eui64_line ,
66 .Nm eui64_aton ,
67 .Nm eui64_ntoa ,
68 .Nm eui64_ntohost ,
69 .Nm eui64_hostton
70 .Nd IEEE EUI-64 conversion and lookup routines
71 .Sh LIBRARY
72 .Lb libc
73 .Sh SYNOPSIS
74 .In sys/types.h
75 .In sys/eui64.h
76 .\" .Ft int
77 .\" .Fn eui64_line "const char *l" "struct eui64 *e" "char *hostname" "size_t len"
78 .Ft int
79 .Fn eui64_aton "const char *a" "struct eui64 *e"
80 .Ft int
81 .Fn eui64_ntoa "const struct eui64 *id" "char *a" "size_t len"
82 .Ft int
83 .Fn eui64_ntohost "char *hostname" "size_t len" "const struct eui64 *id"
84 .Ft int
85 .Fn eui64_hostton "const char *hostname" "struct eui64 *id"
86 .Sh DESCRIPTION
87 These functions operate on IEEE EUI-64s using an
88 .Vt eui64
89 structure, which is defined in the header file
90 .In sys/eui64.h :
91 .Bd -literal -offset indent
92 /*
93 * The number of bytes in an EUI-64.
94 */
95 #define EUI64_LEN 8
97 /*
98 * Structure of an IEEE EUI-64.
99 */
100 struct eui64 {
101 u_char octet[EUI64_LEN];
102 };
103 .Ed
104 .\" .Pp
105 .\" The function
106 .\" .Fn eui64_line
107 .\" scans
108 .\" .Fa l ,
109 .\" an
110 .\" .Tn ASCII
111 .\" string in
112 .\" .Xr eui64 5
113 .\" format and sets
114 .\" .Fa e
115 .\" to the EUI-64 specified in the string and
116 .\" .Fa h
117 .\" to the hostname.
118 .\" This function is used to parse lines from
119 .\" .Pa /etc/eui64
120 .\" into their component parts.
121 .Pp
122 The
123 .Fn eui64_aton
124 function converts an
125 .Tn ASCII
126 representation of an EUI-64 into an
127 .Vt eui64
128 structure.
129 Likewise,
130 .Fn eui64_ntoa
131 converts an EUI-64 specified as an
132 .Vt eui64
133 structure into an
134 .Tn ASCII
135 string.
136 .Pp
137 The
138 .Fn eui64_ntohost
139 and
140 .Fn eui64_hostton
141 functions map EUI-64s to their corresponding hostnames
142 as specified in the
143 .Pa /etc/eui64
144 database.
145 The
146 .Fn eui64_ntohost
147 function
148 converts from EUI-64 to hostname, and
149 .Fn eui64_hostton
150 converts from hostname to EUI-64.
151 .Sh RETURN VALUES
152 .\" The
153 .\" .Fn eui64_line
154 .\" function
155 .\" returns zero on success and non-zero if it was unable to parse
156 .\" any part of the supplied line
157 .\" .Fa l .
158 .\" It returns the extracted EUI-64 in the supplied
159 .\" .Vt eui64
160 .\" structure
161 .\" .Fa e
162 .\" and the hostname in the supplied string
163 .\" .Fa h .
164 .\" .Pp
165 On success,
166 .Fn eui64_ntoa
167 returns a pointer to a string containing an
168 .Tn ASCII
169 representation of an EUI-64.
170 If it is unable to convert
171 the supplied
172 .Vt eui64
173 structure, it returns a
174 .Dv NULL
175 pointer.
176 Likewise,
177 .Fn eui64_aton
178 returns a pointer to an
179 .Vt eui64
180 structure on success and a
181 .Dv NULL
182 pointer on failure.
183 .Pp
184 The
185 .Fn eui64_ntohost
186 and
187 .Fn eui64_hostton
188 functions both return zero on success or non-zero if they were
189 unable to find a match in the
190 .Pa /etc/eui64
191 database.
192 .Sh NOTES
193 The user must insure that the hostname strings passed to the
194 .\" .Fn eui64_line ,
195 .Fn eui64_ntohost
196 and
197 .Fn eui64_hostton
198 functions are large enough to contain the returned hostnames.
199 .Sh NIS INTERACTION
200 If the
201 .Pa /etc/eui64
202 contains a line with a single
203 .Ql +
204 in it, the
205 .Fn eui64_ntohost
206 and
207 .Fn eui64_hostton
208 functions will attempt to consult the NIS
209 .Pa eui64.byname
210 and
211 .Pa eui64.byid
212 maps in addition to the data in the
213 .Pa /etc/eui64
214 file.
215 .Sh SEE ALSO
216 .Xr firewire 4 ,
217 .Xr eui64 5 ,
218 .Xr yp 8
219 .Sh HISTORY
220 These functions first appears in
221 .Fx 5.3 .
222 They are derived from the
223 .Xr ethers 3
224 family of functions.
225 .Sh BUGS
226 The
227 .Fn eui64_aton
228 and
229 .Fn eui64_ntoa
230 functions returns values that are stored in static memory areas
231 which may be overwritten the next time they are called.