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$ 58.\" 59.Dd March 4, 2004 60.Dt EUI64 3 61.Os 62.Sh NAME 63.Nm eui64 , 64.\" .Nm eui64_line , 65.Nm eui64_aton , 66.Nm eui64_ntoa , 67.Nm eui64_ntohost , 68.Nm eui64_hostton 69.Nd IEEE EUI-64 conversion and lookup routines 70.Sh LIBRARY 71.Lb libc 72.Sh SYNOPSIS 73.In sys/types.h 74.In sys/eui64.h 75.\" .Ft int 76.\" .Fn eui64_line "const char *l" "struct eui64 *e" "char *hostname" "size_t len" 77.Ft int 78.Fn eui64_aton "const char *a" "struct eui64 *e" 79.Ft int 80.Fn eui64_ntoa "const struct eui64 *id" "char *a" "size_t len" 81.Ft int 82.Fn eui64_ntohost "char *hostname" "size_t len" "const struct eui64 *id" 83.Ft int 84.Fn eui64_hostton "const char *hostname" "struct eui64 *id" 85.Sh DESCRIPTION 86These functions operate on IEEE EUI-64s using an 87.Vt eui64 88structure, which is defined in the header file 89.In sys/eui64.h : 90.Bd -literal -offset indent 91/* 92 * The number of bytes in an EUI-64. 93 */ 94#define EUI64_LEN 8 95 96/* 97 * Structure of an IEEE EUI-64. 98 */ 99struct eui64 { 100 u_char octet[EUI64_LEN]; 101}; 102.Ed 103.\" .Pp 104.\" The function 105.\" .Fn eui64_line 106.\" scans 107.\" .Fa l , 108.\" an 109.\" .Tn ASCII 110.\" string in 111.\" .Xr eui64 5 112.\" format and sets 113.\" .Fa e 114.\" to the EUI-64 specified in the string and 115.\" .Fa h 116.\" to the hostname. 117.\" This function is used to parse lines from 118.\" .Pa /etc/eui64 119.\" into their component parts. 120.Pp 121The 122.Fn eui64_aton 123function converts an 124.Tn ASCII 125representation of an EUI-64 into an 126.Vt eui64 127structure. 128Likewise, 129.Fn eui64_ntoa 130converts an EUI-64 specified as an 131.Vt eui64 132structure into an 133.Tn ASCII 134string. 135.Pp 136The 137.Fn eui64_ntohost 138and 139.Fn eui64_hostton 140functions map EUI-64s to their corresponding hostnames 141as specified in the 142.Pa /etc/eui64 143database. 144The 145.Fn eui64_ntohost 146function 147converts from EUI-64 to hostname, and 148.Fn eui64_hostton 149converts from hostname to EUI-64. 150.Sh RETURN VALUES 151.\" The 152.\" .Fn eui64_line 153.\" function 154.\" returns zero on success and non-zero if it was unable to parse 155.\" any part of the supplied line 156.\" .Fa l . 157.\" It returns the extracted EUI-64 in the supplied 158.\" .Vt eui64 159.\" structure 160.\" .Fa e 161.\" and the hostname in the supplied string 162.\" .Fa h . 163.\" .Pp 164On success, 165.Fn eui64_ntoa 166returns a pointer to a string containing an 167.Tn ASCII 168representation of an EUI-64. 169If it is unable to convert 170the supplied 171.Vt eui64 172structure, it returns a 173.Dv NULL 174pointer. 175Likewise, 176.Fn eui64_aton 177returns a pointer to an 178.Vt eui64 179structure on success and a 180.Dv NULL 181pointer on failure. 182.Pp 183The 184.Fn eui64_ntohost 185and 186.Fn eui64_hostton 187functions both return zero on success or non-zero if they were 188unable to find a match in the 189.Pa /etc/eui64 190database. 191.Sh NOTES 192The user must ensure that the hostname strings passed to the 193.\" .Fn eui64_line , 194.Fn eui64_ntohost 195and 196.Fn eui64_hostton 197functions are large enough to contain the returned hostnames. 198.Sh NIS INTERACTION 199If the 200.Pa /etc/eui64 201contains a line with a single 202.Ql + 203in it, the 204.Fn eui64_ntohost 205and 206.Fn eui64_hostton 207functions will attempt to consult the NIS 208.Pa eui64.byname 209and 210.Pa eui64.byid 211maps in addition to the data in the 212.Pa /etc/eui64 213file. 214.Sh SEE ALSO 215.Xr firewire 4 , 216.Xr eui64 5 , 217.Xr yp 8 218.Sh HISTORY 219These functions first appears in 220.Fx 5.3 . 221They are derived from the 222.Xr ethers 3 223family of functions. 224.Sh BUGS 225The 226.Fn eui64_aton 227and 228.Fn eui64_ntoa 229functions returns values that are stored in static memory areas 230which may be overwritten the next time they are called. 231