source: rtems/c/src/exec/libnetworking/libc/addr2ascii.3 @ 96b39164

4.104.114.84.95
Last change on this file since 96b39164 was 96b39164, checked in by Joel Sherrill <joel.sherrill@…>, on 08/20/98 at 21:56:40

Added CVS Ids

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