projects / dragonfly.git / blame_incremental
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (non-incremental) | history | HEAD
- Uniformly use .In for header file references.
[dragonfly.git] / lib / libc / net / eui64.3
... / ...
CommitLineData
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.3 2004/07/07 20:15:31 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
87These functions operate on IEEE EUI-64s using an
88.Vt eui64
89structure, 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
96
97/*
98 * Structure of an IEEE EUI-64.
99 */
100struct 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
122The
123.Fn eui64_aton
124function converts an
125.Tn ASCII
126representation of an EUI-64 into an
127.Vt eui64
128structure.
129Likewise,
130.Fn eui64_ntoa
131converts an EUI-64 specified as an
132.Vt eui64
133structure into an
134.Tn ASCII
135string.
136.Pp
137The
138.Fn eui64_ntohost
139and
140.Fn eui64_hostton
141functions map EUI-64s to their corresponding hostnames
142as specified in the
143.Pa /etc/eui64
144database.
145The
146.Fn eui64_ntohost
147function
148converts from EUI-64 to hostname, and
149.Fn eui64_hostton
150converts 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
165On success,
166.Fn eui64_ntoa
167returns a pointer to a string containing an
168.Tn ASCII
169representation of an EUI-64.
170If it is unable to convert
171the supplied
172.Vt eui64
173structure, it returns a
174.Dv NULL
175pointer.
176Likewise,
177.Fn eui64_aton
178returns a pointer to an
179.Vt eui64
180structure on success and a
181.Dv NULL
182pointer on failure.
183.Pp
184The
185.Fn eui64_ntohost
186and
187.Fn eui64_hostton
188functions both return zero on success or non-zero if they were
189unable to find a match in the
190.Pa /etc/eui64
191database.
192.Sh NOTES
193The user must insure that the hostname strings passed to the
194.\" .Fn eui64_line ,
195.Fn eui64_ntohost
196and
197.Fn eui64_hostton
198functions are large enough to contain the returned hostnames.
199.Sh NIS INTERACTION
200If the
201.Pa /etc/eui64
202contains a line with a single
203.Ql +
204in it, the
205.Fn eui64_ntohost
206and
207.Fn eui64_hostton
208functions will attempt to consult the NIS
209.Pa eui64.byname
210and
211.Pa eui64.byid
212maps in addition to the data in the
213.Pa /etc/eui64
214file.
215.Sh SEE ALSO
216.Xr firewire 4 ,
217.Xr eui64 5 ,
218.Xr yp 8
219.Sh HISTORY
220These functions first appears in
221.Fx 5.3 .
222They are derived from the
223.Xr ethers 3
224family of functions.
225.Sh BUGS
226The
227.Fn eui64_aton
228and
229.Fn eui64_ntoa
230functions returns values that are stored in static memory areas
231which may be overwritten the next time they are called.
DragonFly Project Source