net/FreeBSD/addr2ascii.3

   1 .\"
   2 .\" Copyright 1996 Massachusetts Institute of Technology
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this software and
   5 .\" its documentation for any purpose and without fee is hereby
   6 .\" granted, provided that both the above copyright notice and this
   7 .\" permission notice appear in all copies, that both the above
   8 .\" copyright notice and this permission notice appear in all
   9 .\" supporting documentation, and that the name of M.I.T. not be used
  10 .\" in advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.  M.I.T. makes
  12 .\" no representations about the suitability of this software for any
  13 .\" purpose.  It is provided "as is" without express or implied
  14 .\" warranty.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
  17 .\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
  20 .\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  21 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  22 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
  23 .\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
  24 .\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  25 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  26 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\"     $ANA: addr2ascii.3,v 1.1 1996/06/13 18:41:46 wollman Exp $
  30 .\" $FreeBSD: src/lib/libc/net/addr2ascii.3,v 1.17 2004/10/09 17:13:58 maxim Exp $
  31 .\"
  32 .Dd June 13, 1996
  33 .Dt ADDR2ASCII 3
  34 .Os
  35 .Sh NAME
  36 .Nm addr2ascii ,
  37 .Nm ascii2addr
  38 .Nd Generic address formatting routines
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In arpa/inet.h
  43 .Ft "char *"
  44 .Fn addr2ascii "int af" "const void *addrp" "int len" "char *buf"
  45 .Ft int
  46 .Fn ascii2addr "int af" "const char *ascii" "void *result"
  47 .Sh DESCRIPTION
  48 The routines
  49 .Fn addr2ascii
  50 and
  51 .Fn ascii2addr
  52 are used to convert network addresses between binary form and a
  53 printable form appropriate to the address family.
  54 Both functions take
  55 an
  56 .Fa af
  57 argument, specifying the address family to be used in the conversion
  58 process.
  59 (Currently, only the
  60 .Dv AF_INET
  61 and
  62 .Dv AF_LINK
  63 address families are supported.)
  64 .Pp
  65 The
  66 .Fn addr2ascii
  67 function
  68 is used to convert binary, network-format addresses into printable
  69 form.
  70 In addition to
  71 .Fa af ,
  72 there are three other arguments.
  73 The
  74 .Fa addrp
  75 argument is a pointer to the network address to be converted.
  76 The
  77 .Fa len
  78 argument is the length of the address.
  79 The
  80 .Fa buf
  81 argument is an optional pointer to a caller-allocated buffer to hold
  82 the result; if a null pointer is passed,
  83 .Fn addr2ascii
  84 uses a statically-allocated buffer.
  85 .Pp
  86 The
  87 .Fn ascii2addr
  88 function performs the inverse operation to
  89 .Fn addr2ascii .
  90 In addition to
  91 .Fa af ,
  92 it takes two arguments,
  93 .Fa ascii
  94 and
  95 .Fa result .
  96 The
  97 .Fa ascii
  98 argument is a pointer to the string which is to be converted into
  99 binary.
 100 The
 101 .Fa result
 102 argument is a pointer to an appropriate network address structure for
 103 the specified family.
 104 .Pp
 105 The following gives the appropriate structure to use for binary
 106 addresses in the specified family:
 107 .Pp
 108 .Bl -tag -width AF_INETxxxx -compact
 109 .It Dv AF_INET
 110 .Li struct in_addr
 111 (in
 112 .In arpa/inet.h )
 113 .It Dv AF_LINK
 114 .Li struct sockaddr_dl
 115 (in
 116 .In net/if_dl.h )
 117 .\" .It Dv AF_INET6
 118 .\" .Li struct in6_addr
 119 .\" (in
 120 .\" .In netinet6/in6.h )
 121 .El
 122 .Pp
 123 .Dv AF_INET and AF_LINK constants are defined in
 124 .In sys/socket.h
 125 .Sh RETURN VALUES
 126 The
 127 .Fn addr2ascii
 128 function returns the address of the buffer it was passed, or a static
 129 buffer if the a null pointer was passed; on failure, it returns a null
 130 pointer.
 131 The
 132 .Fn ascii2addr
 133 function returns the length of the binary address in bytes, or -1 on
 134 failure.
 135 .Sh EXAMPLES
 136 The
 137 .Xr inet 3
 138 functions
 139 .Fn inet_ntoa
 140 and
 141 .Fn inet_aton
 142 could be implemented thusly:
 143 .Bd -literal -offset indent
 144 #include <sys/socket.h>
 145 #include <arpa/inet.h>
 146
 147 char *
 148 inet_ntoa(struct in_addr addr)
 149 {
 150         return addr2ascii(AF_INET, &addr, sizeof addr, 0);
 151 }
 152
 153 int
 154 inet_aton(const char *ascii, struct in_addr *addr)
 155 {
 156         return (ascii2addr(AF_INET, ascii, addr)
 157             == sizeof(*addr));
 158 }
 159 .Ed
 160 .Pp
 161 In actuality, this cannot be done because
 162 .Fn addr2ascii
 163 and
 164 .Fn ascii2addr
 165 are implemented in terms of the
 166 .Xr inet 3
 167 functions, rather than the other way around.
 168 .Sh ERRORS
 169 When a failure is returned,
 170 .Li errno
 171 is set to one of the following values:
 172 .Bl -tag -width Er
 173 .It Bq Er ENAMETOOLONG
 174 The
 175 .Fn addr2ascii
 176 routine was passed a
 177 .Fa len
 178 argument which was inappropriate for the address family given by
 179 .Fa af .
 180 .It Bq Er EPROTONOSUPPORT
 181 Either routine was passed an
 182 .Fa af
 183 argument other than
 184 .Dv AF_INET
 185 or
 186 .Dv AF_LINK .
 187 .It Bq Er EINVAL
 188 The string passed to
 189 .Fn ascii2addr
 190 was improperly formatted for address family
 191 .Fa af .
 192 .El
 193 .Sh SEE ALSO
 194 .Xr inet 3 ,
 195 .Xr linkaddr 3 ,
 196 .Xr inet 4
 197 .Sh HISTORY
 198 An interface close to this one was originally suggested by Craig
 199 Partridge.
 200 This particular interface originally appeared in the
 201 .Tn INRIA
 202 .Tn IPv6
 203 implementation.
 204 .Sh AUTHORS
 205 Code and documentation by
 206 .An Garrett A. Wollman ,
 207 MIT Laboratory for Computer Science.
 208 .Sh BUGS
 209 The original implementations supported IPv6.
 210 This support should
 211 eventually be resurrected.
 212 The
 213 .Tn NRL
 214 implementation also included support for the
 215 .Dv AF_ISO
 216 and
 217 .Dv AF_NS
 218 address families.
 219 .Pp
 220 The genericity of this interface is somewhat questionable.
 221 A truly
 222 generic interface would provide a means for determining the length of
 223 the buffer to be used so that it could be dynamically allocated, and
 224 would always require a
 225 .Dq Li "struct sockaddr"
 226 to hold the binary address.
 227 Unfortunately, this is incompatible with existing
 228 practice.
 229 This limitation means that a routine for printing network
 230 addresses from arbitrary address families must still have internal
 231 knowledge of the maximum buffer length needed and the appropriate part
 232 of the address to use as the binary address.