2 .\" Copyright 1996 Massachusetts Institute of Technology
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
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
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/libc/net/addr2ascii.3,v 1.4 2007/06/30 19:03:52 swildner Exp $
39 .Nd Generic address formatting routines
47 .Fn addr2ascii "int af" "const void *addrp" "int len" "char *buf"
49 .Fn ascii2addr "int af" "const char *ascii" "void *result"
55 are used to convert network addresses between binary form and a
56 printable form appropriate to the address family. Both functions take
59 argument, specifying the address family to be used in the conversion
65 address families are supported.)
70 is used to convert binary, network-format addresses into printable
73 there are three other arguments. The
75 argument is a pointer to the network address to be converted.
78 argument is the length of the address. The
80 argument is an optional pointer to a caller-allocated buffer to hold
81 the result; if a null pointer is passed,
83 uses a statically-allocated buffer.
87 function performs the inverse operation to
91 it takes two parameters,
97 parameter is a pointer to the string which is to be converted into
100 parameter is a pointer to an appropriate network address structure for
101 the specified family.
103 The following gives the appropriate structure to use for binary
104 addresses in the specified family:
106 .Bl -tag -width AF_INETxxxx -compact
112 .Li struct sockaddr_dl
116 .\" .Li struct in6_addr
118 .\" .In netinet6/in6.h )
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
128 function returns the length of the binary address in bytes, or -1 on
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>
145 inet_ntoa(struct in_addr addr)
147 return addr2ascii(AF_INET, &addr, sizeof addr, 0);
151 inet_aton(const char *ascii, struct in_addr *addr)
153 return (ascii2addr(AF_INET, ascii, addr)
158 In actuality, this cannot be done because
162 are implemented in terms of the
164 functions, rather than the other way around.
166 When a failure is returned,
168 is set to one of the following values:
170 .It Bq Er ENAMETOOLONG
175 parameter which was inappropriate for the address family given by
177 .It Bq Er EPROTONOSUPPORT
178 Either routine was passed an
187 was improperly formatted for address family
195 An interface close to this one was originally suggested by Craig
196 Partridge. This particular interface originally appeared in the
201 Code and documentation by
202 .An Garrett A. Wollman ,
203 MIT Laboratory for Computer Science.
205 The original implementations supported IPv6. This support should
206 eventually be resurrected. The
208 implementation also included support for the
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.