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