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