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