]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> |
cd1aabe6 | 2 | .\" and Copyright (c) 2008 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" References: RFC 2553 | |
460495ca | 27 | .TH INET_PTON 3 2015-08-08 "Linux" "Linux Programmer's Manual" |
fea681da | 28 | .SH NAME |
cd1aabe6 | 29 | inet_pton \- convert IPv4 and IPv6 addresses from text to binary form |
fea681da MK |
30 | .SH SYNOPSIS |
31 | .nf | |
fea681da | 32 | .B #include <arpa/inet.h> |
c8250206 | 33 | |
fea681da | 34 | .BI "int inet_pton(int " "af" ", const char *" "src" ", void *" "dst" ); |
c8250206 | 35 | .fi |
fea681da MK |
36 | .SH DESCRIPTION |
37 | This function converts the character string | |
38 | .I src | |
39 | into a network address structure in the | |
40 | .I af | |
41 | address family, then | |
42 | copies | |
43 | the network address structure to | |
44 | .IR dst . | |
cd1aabe6 MK |
45 | The |
46 | .I af | |
47 | argument must be either | |
48 | .B AF_INET | |
49 | or | |
50 | .BR AF_INET6 . | |
fea681da | 51 | .PP |
fea681da MK |
52 | The following address families are currently supported: |
53 | .TP | |
54 | .B AF_INET | |
55 | .I src | |
56 | points to a character string containing an IPv4 network address in | |
cd1aabe6 MK |
57 | dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP", where |
58 | .I ddd | |
59 | is a decimal number of up to three digits in the range 0 to 255. | |
60 | The address is converted to a | |
fea681da MK |
61 | .I struct in_addr |
62 | and copied to | |
a5e0a0e4 | 63 | .IR dst , |
fea681da MK |
64 | which must be |
65 | .I sizeof(struct in_addr) | |
cd1aabe6 | 66 | (4) bytes (32 bits) long. |
fea681da MK |
67 | .TP |
68 | .B AF_INET6 | |
69 | .I src | |
cd1aabe6 MK |
70 | points to a character string containing an IPv6 network address. |
71 | The address is converted to a | |
fea681da MK |
72 | .I struct in6_addr |
73 | and copied to | |
a5e0a0e4 | 74 | .IR dst , |
fea681da MK |
75 | which must be |
76 | .I sizeof(struct in6_addr) | |
cd1aabe6 MK |
77 | (16) bytes (128 bits) long. |
78 | The allowed formats for IPv6 addresses follow these rules: | |
79 | .RS | |
80 | .IP 1. 3 | |
81 | The preferred format is | |
8dcc7633 | 82 | .IR x:x:x:x:x:x:x:x . |
cd1aabe6 MK |
83 | This form consists of eight hexadecimal numbers, |
84 | each of which expresses a 16-bit value (i.e., each | |
85 | .I x | |
86 | can be up to 4 hex digits). | |
87 | .IP 2. | |
88 | A series of contiguous zero values in the preferred format | |
89 | can be abbreviated to | |
90 | .IR :: . | |
91 | Only one instance of | |
92 | .I :: | |
93 | can occur in an address. | |
94 | For example, the loopback address | |
95 | .I 0:0:0:0:0:0:0:1 | |
96 | can be abbreviated as | |
97 | .IR ::1 . | |
fb30b096 | 98 | The wildcard address, consisting of all zeros, can be written as |
cd1aabe6 MK |
99 | .IR :: . |
100 | .IP 3. | |
101 | An alternate format is useful for expressing IPv4-mapped IPv6 addresses. | |
102 | This form is written as | |
103 | .IR x:x:x:x:x:x:d.d.d.d , | |
104 | where the six leading | |
105 | .IR x s | |
106 | are hexadecimal values that define the six most-significant | |
107 | 16-bit pieces of the address (i.e., 96 bits), and the | |
108 | .IR d s | |
109 | express a value in dotted-decimal notation that | |
110 | defines the least significant 32 bits of the address. | |
111 | An example of such an address is | |
112 | .IR ::FFFF:204.152.189.116 . | |
113 | .RE | |
114 | .IP | |
115 | See RFC 2373 for further details on the representation of IPv6 addresses. | |
47297adb | 116 | .SH RETURN VALUE |
e511ffb6 | 117 | .BR inet_pton () |
cd1aabe6 | 118 | returns 1 on success (network address was successfully converted). |
fea681da MK |
119 | 0 is returned if |
120 | .I src | |
121 | does not contain a character string representing a valid network | |
122 | address in the specified address family. | |
cd1aabe6 MK |
123 | If |
124 | .I af | |
125 | does not contain a valid address family, \-1 is returned and | |
126 | .I errno | |
127 | is set to | |
128 | .BR EAFNOSUPPORT . | |
b4ccbb8f PH |
129 | .SH ATTRIBUTES |
130 | For an explanation of the terms used in this section, see | |
131 | .BR attributes (7). | |
132 | .TS | |
133 | allbox; | |
134 | lb lb lb | |
135 | l l l. | |
136 | Interface Attribute Value | |
137 | T{ | |
138 | .BR inet_pton () | |
139 | T} Thread safety MT-Safe locale | |
140 | .TE | |
47297adb | 141 | .SH CONFORMING TO |
9d47ddf3 | 142 | POSIX.1-2001, POSIX.1-2008. |
cd1aabe6 MK |
143 | .SH NOTES |
144 | Unlike | |
145 | .BR inet_aton (3) | |
146 | and | |
147 | .BR inet_addr (3), | |
148 | .BR inet_pton () | |
149 | supports IPv6 addresses. | |
150 | On the other hand, | |
151 | .BR inet_pton () | |
33a0ccb2 | 152 | accepts only IPv4 addresses in dotted-decimal notation, whereas |
cd1aabe6 MK |
153 | .BR inet_aton (3) |
154 | and | |
155 | .BR inet_addr (3) | |
156 | allow the more general numbers-and-dots notation (hexadecimal | |
157 | and octal number formats, and formats that don't require all | |
158 | four bytes to be explicitly written). | |
159 | For an interface that handles both IPv6 addresses, and IPv4 | |
160 | addresses in numbers-and-dots notation, see | |
161 | .BR getaddrinfo (3). | |
25768803 MK |
162 | .SH BUGS |
163 | .B AF_INET6 | |
164 | does not recognize IPv4 addresses. | |
165 | An explicit IPv4-mapped IPv6 address must be supplied in | |
166 | .I src | |
167 | instead. | |
cd1aabe6 MK |
168 | .SH EXAMPLE |
169 | The program below demonstrates the use of | |
170 | .BR inet_pton () | |
171 | and | |
172 | .BR inet_ntop (3). | |
173 | Here are some example runs: | |
174 | .in +4n | |
175 | .nf | |
176 | ||
b43a3b30 | 177 | .RB "$" " ./a.out i6 0:0:0:0:0:0:0:0" |
cd1aabe6 | 178 | :: |
b43a3b30 | 179 | .RB "$" " ./a.out i6 1:0:0:0:0:0:0:8" |
cd1aabe6 | 180 | 1::8 |
b43a3b30 | 181 | .RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116" |
cd1aabe6 | 182 | ::ffff:204.152.189.116 |
cd1aabe6 MK |
183 | .fi |
184 | .in | |
9c330504 | 185 | .SS Program source |
d84d0300 | 186 | \& |
cd1aabe6 MK |
187 | .nf |
188 | #include <arpa/inet.h> | |
189 | #include <stdio.h> | |
190 | #include <stdlib.h> | |
191 | #include <string.h> | |
192 | ||
193 | int | |
194 | main(int argc, char *argv[]) | |
195 | { | |
196 | unsigned char buf[sizeof(struct in6_addr)]; | |
197 | int domain, s; | |
198 | char str[INET6_ADDRSTRLEN]; | |
199 | ||
200 | if (argc != 3) { | |
201 | fprintf(stderr, "Usage: %s {i4|i6|<num>} string\\n", argv[0]); | |
202 | exit(EXIT_FAILURE); | |
203 | } | |
204 | ||
205 | domain = (strcmp(argv[1], "i4") == 0) ? AF_INET : | |
206 | (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]); | |
207 | ||
208 | s = inet_pton(domain, argv[2], buf); | |
209 | if (s <= 0) { | |
210 | if (s == 0) | |
211 | fprintf(stderr, "Not in presentation format"); | |
212 | else | |
213 | perror("inet_pton"); | |
214 | exit(EXIT_FAILURE); | |
215 | } | |
216 | ||
217 | if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) { | |
218 | perror("inet_ntop"); | |
219 | exit(EXIT_FAILURE); | |
cd60dedd | 220 | } |
cd1aabe6 MK |
221 | |
222 | printf("%s\\n", str); | |
223 | ||
224 | exit(EXIT_SUCCESS); | |
225 | } | |
226 | .fi | |
47297adb | 227 | .SH SEE ALSO |
cd1aabe6 MK |
228 | .BR getaddrinfo (3), |
229 | .BR inet (3), | |
e37e3282 | 230 | .BR inet_ntop (3) |