lib/libc/net/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.7.2.5 2001/12/14 18:33:55 ru 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 sys/types.h
  43 .In netinet/in.h
  44 .In arpa/inet.h
  45 .Ft "char *"
  46 .Fn addr2ascii "int af" "const void *addrp" "int len" "char *buf"
  47 .Ft int
  48 .Fn ascii2addr "int af" "const char *ascii" "void *result"
  49 .Sh DESCRIPTION
  50 The routines
  51 .Fn addr2ascii
  52 and
  53 .Fn ascii2addr
  54 are used to convert network addresses between binary form and a
  55 printable form appropriate to the address family.  Both functions take
  56 an
  57 .Fa af
  58 argument, specifying the address family to be used in the conversion
  59 process.
  60 (Currently, only the
  61 .Dv AF_INET
  62 and
  63 .Dv AF_LINK
  64 address families are supported.)
  65 .Pp
  66 The
  67 .Fn addr2ascii
  68 function
  69 is used to convert binary, network-format addresses into printable
  70 form.  In addition to
  71 .Fa af ,
  72 there are three other arguments.  The
  73 .Fa addrp
  74 argument is a pointer to the network address to be converted.
  75 The
  76 .Fa len
  77 argument is the length of the address.  The
  78 .Fa buf
  79 argument is an optional pointer to a caller-allocated buffer to hold
  80 the result; if a null pointer is passed,
  81 .Fn addr2ascii
  82 uses a statically-allocated buffer.
  83 .Pp
  84 The
  85 .Fn ascii2addr
  86 function performs the inverse operation to
  87 .Fn addr2ascii .
  88 In addition to
  89 .Fa af ,
  90 it takes two parameters,
  91 .Fa ascii
  92 and
  93 .Fa result .
  94 The
  95 .Fa ascii
  96 parameter is a pointer to the string which is to be converted into
  97 binary.  The
  98 .Fa result
  99 parameter is a pointer to an appropriate network address structure for
 100 the specified family.
 101 .Pp
 102 The following gives the appropriate structure to use for binary
 103 addresses in the specified family:
 104 .Pp
 105 .Bl -tag -width AF_INETxxxx -compact
 106 .It Dv AF_INET
 107 .Li struct in_addr
 108 (in
 109 .Aq Pa netinet/in.h )
 110 .It Dv AF_LINK
 111 .Li struct sockaddr_dl
 112 (in
 113 .Aq Pa net/if_dl.h )
 114 .\" .It Dv AF_INET6
 115 .\" .Li struct in6_addr
 116 .\" (in
 117 .\" .Aq Pa netinet6/in6.h )
 118 .El
 119 .Sh RETURN VALUES
 120 The
 121 .Fn addr2ascii
 122 function returns the address of the buffer it was passed, or a static
 123 buffer if the a null pointer was passed; on failure, it returns a null
 124 pointer.
 125 The
 126 .Fn ascii2addr
 127 function returns the length of the binary address in bytes, or -1 on
 128 failure.
 129 .Sh EXAMPLES
 130 The
 131 .Xr inet 3
 132 functions
 133 .Fn inet_ntoa
 134 and
 135 .Fn inet_aton
 136 could be implemented thusly:
 137 .Bd -literal -offset indent
 138 #include <sys/types.h>
 139 #include <sys/socket.h>
 140 #include <netinet/in.h>
 141 #include <arpa/inet.h>
 142
 143 char *
 144 inet_ntoa(struct in_addr addr)
 145 {
 146         return addr2ascii(AF_INET, &addr, sizeof addr, 0);
 147 }
 148
 149 int
 150 inet_aton(const char *ascii, struct in_addr *addr)
 151 {
 152         return (ascii2addr(AF_INET, ascii, addr)
 153             == sizeof(*addr));
 154 }
 155 .Ed
 156 .Pp
 157 In actuality, this cannot be done because
 158 .Fn addr2ascii
 159 and
 160 .Fn ascii2addr
 161 are implemented in terms of the
 162 .Xr inet 3
 163 functions, rather than the other way around.
 164 .Sh ERRORS
 165 When a failure is returned,
 166 .Li errno
 167 is set to one of the following values:
 168 .Bl -tag -width Er
 169 .It Bq Er ENAMETOOLONG
 170 The
 171 .Fn addr2ascii
 172 routine was passed a
 173 .Fa len
 174 parameter which was inappropriate for the address family given by
 175 .Fa af .
 176 .It Bq Er EPROTONOSUPPORT
 177 Either routine was passed an
 178 .Fa af
 179 parameter other than
 180 .Dv AF_INET
 181 or
 182 .Dv AF_LINK .
 183 .It Bq Er EINVAL
 184 The string passed to
 185 .Fn ascii2addr
 186 was improperly formatted for address family
 187 .Fa af .
 188 .El
 189 .Sh SEE ALSO
 190 .Xr inet 3 ,
 191 .Xr linkaddr 3 ,
 192 .Xr inet 4
 193 .Sh HISTORY
 194 An interface close to this one was originally suggested by Craig
 195 Partridge.  This particular interface originally appeared in the
 196 .Tn INRIA
 197 .Tn IPv6
 198 implementation.
 199 .Sh AUTHORS
 200 Code and documentation by
 201 .An Garrett A. Wollman ,
 202 MIT Laboratory for Computer Science.
 203 .Sh BUGS
 204 The original implementations supported IPv6.  This support should
 205 eventually be resurrected.  The
 206 .Tn NRL
 207 implementation also included support for the
 208 .Dv AF_ISO
 209 and
 210 .Dv AF_NS
 211 address families.
 212 .Pp
 213 The genericity of this interface is somewhat questionable.  A truly
 214 generic interface would provide a means for determining the length of
 215 the buffer to be used so that it could be dynamically allocated, and
 216 would always require a
 217 .Dq Li "struct sockaddr"
 218 to hold the binary address.  Unfortunately, this is incompatible with existing
 219 practice.  This limitation means that a routine for printing network
 220 addresses from arbitrary address families must still have internal
 221 knowledge of the maximum buffer length needed and the appropriate part
 222 of the address to use as the binary address.