lib/libc/net/eui64.3

   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.2 2004/12/26 12:37:07 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 .Aq Pa 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  */
 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 BUGS
 220 The
 221 .Fn eui64_aton
 222 and
 223 .Fn eui64_ntoa
 224 functions returns values that are stored in static memory areas
 225 which may be overwritten the next time they are called.
 226 .Sh HISTORY
 227 These functions first appears in
 228 .Fx 5.3 .
 229 They are derived from the
 230 .Xr ethers 3
 231 family of functions.