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