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$
  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
  86 These functions operate on IEEE EUI-64s using an
  87 .Vt eui64
  88 structure, 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  */
  99 struct  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
 121 The
 122 .Fn eui64_aton
 123 function converts an
 124 .Tn ASCII
 125 representation of an EUI-64 into an
 126 .Vt eui64
 127 structure.
 128 Likewise,
 129 .Fn eui64_ntoa
 130 converts an EUI-64 specified as an
 131 .Vt eui64
 132 structure into an
 133 .Tn ASCII
 134 string.
 135 .Pp
 136 The
 137 .Fn eui64_ntohost
 138 and
 139 .Fn eui64_hostton
 140 functions map EUI-64s to their corresponding hostnames
 141 as specified in the
 142 .Pa /etc/eui64
 143 database.
 144 The
 145 .Fn eui64_ntohost
 146 function
 147 converts from EUI-64 to hostname, and
 148 .Fn eui64_hostton
 149 converts 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
 164 On success,
 165 .Fn eui64_ntoa
 166 returns a pointer to a string containing an
 167 .Tn ASCII
 168 representation of an EUI-64.
 169 If it is unable to convert
 170 the supplied
 171 .Vt eui64
 172 structure, it returns a
 173 .Dv NULL
 174 pointer.
 175 Likewise,
 176 .Fn eui64_aton
 177 returns a pointer to an
 178 .Vt eui64
 179 structure on success and a
 180 .Dv NULL
 181 pointer on failure.
 182 .Pp
 183 The
 184 .Fn eui64_ntohost
 185 and
 186 .Fn eui64_hostton
 187 functions both return zero on success or non-zero if they were
 188 unable to find a match in the
 189 .Pa /etc/eui64
 190 database.
 191 .Sh NOTES
 192 The user must ensure that the hostname strings passed to the
 193 .\" .Fn eui64_line ,
 194 .Fn eui64_ntohost
 195 and
 196 .Fn eui64_hostton
 197 functions are large enough to contain the returned hostnames.
 198 .Sh NIS INTERACTION
 199 If the
 200 .Pa /etc/eui64
 201 contains a line with a single
 202 .Ql +
 203 in it, the
 204 .Fn eui64_ntohost
 205 and
 206 .Fn eui64_hostton
 207 functions will attempt to consult the NIS
 208 .Pa eui64.byname
 209 and
 210 .Pa eui64.byid
 211 maps in addition to the data in the
 212 .Pa /etc/eui64
 213 file.
 214 .Sh SEE ALSO
 215 .Xr firewire 4 ,
 216 .Xr eui64 5 ,
 217 .Xr yp 8
 218 .Sh HISTORY
 219 These functions first appears in
 220 .Fx 5.3 .
 221 They are derived from the
 222 .Xr ethers 3
 223 family of functions.