]>
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 | |
4b8c67d9 | 27 | .TH INET_PTON 3 2017-09-15 "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> |
f90f031e | 33 | .PP |
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 . | |
04fd9903 SP |
51 | .IR dst |
52 | is written in network byte order. | |
fea681da | 53 | .PP |
fea681da MK |
54 | The following address families are currently supported: |
55 | .TP | |
56 | .B AF_INET | |
57 | .I src | |
58 | points to a character string containing an IPv4 network address in | |
cd1aabe6 MK |
59 | dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP", where |
60 | .I ddd | |
61 | is a decimal number of up to three digits in the range 0 to 255. | |
62 | The address is converted to a | |
fea681da MK |
63 | .I struct in_addr |
64 | and copied to | |
a5e0a0e4 | 65 | .IR dst , |
fea681da MK |
66 | which must be |
67 | .I sizeof(struct in_addr) | |
cd1aabe6 | 68 | (4) bytes (32 bits) long. |
fea681da MK |
69 | .TP |
70 | .B AF_INET6 | |
71 | .I src | |
cd1aabe6 MK |
72 | points to a character string containing an IPv6 network address. |
73 | The address is converted to a | |
fea681da MK |
74 | .I struct in6_addr |
75 | and copied to | |
a5e0a0e4 | 76 | .IR dst , |
fea681da MK |
77 | which must be |
78 | .I sizeof(struct in6_addr) | |
cd1aabe6 MK |
79 | (16) bytes (128 bits) long. |
80 | The allowed formats for IPv6 addresses follow these rules: | |
81 | .RS | |
82 | .IP 1. 3 | |
83 | The preferred format is | |
8dcc7633 | 84 | .IR x:x:x:x:x:x:x:x . |
cd1aabe6 MK |
85 | This form consists of eight hexadecimal numbers, |
86 | each of which expresses a 16-bit value (i.e., each | |
87 | .I x | |
88 | can be up to 4 hex digits). | |
89 | .IP 2. | |
90 | A series of contiguous zero values in the preferred format | |
91 | can be abbreviated to | |
92 | .IR :: . | |
93 | Only one instance of | |
94 | .I :: | |
95 | can occur in an address. | |
96 | For example, the loopback address | |
97 | .I 0:0:0:0:0:0:0:1 | |
98 | can be abbreviated as | |
99 | .IR ::1 . | |
fb30b096 | 100 | The wildcard address, consisting of all zeros, can be written as |
cd1aabe6 MK |
101 | .IR :: . |
102 | .IP 3. | |
103 | An alternate format is useful for expressing IPv4-mapped IPv6 addresses. | |
104 | This form is written as | |
105 | .IR x:x:x:x:x:x:d.d.d.d , | |
106 | where the six leading | |
107 | .IR x s | |
108 | are hexadecimal values that define the six most-significant | |
109 | 16-bit pieces of the address (i.e., 96 bits), and the | |
110 | .IR d s | |
111 | express a value in dotted-decimal notation that | |
112 | defines the least significant 32 bits of the address. | |
113 | An example of such an address is | |
114 | .IR ::FFFF:204.152.189.116 . | |
115 | .RE | |
116 | .IP | |
117 | See RFC 2373 for further details on the representation of IPv6 addresses. | |
47297adb | 118 | .SH RETURN VALUE |
e511ffb6 | 119 | .BR inet_pton () |
cd1aabe6 | 120 | returns 1 on success (network address was successfully converted). |
fea681da MK |
121 | 0 is returned if |
122 | .I src | |
123 | does not contain a character string representing a valid network | |
124 | address in the specified address family. | |
cd1aabe6 MK |
125 | If |
126 | .I af | |
127 | does not contain a valid address family, \-1 is returned and | |
128 | .I errno | |
129 | is set to | |
130 | .BR EAFNOSUPPORT . | |
b4ccbb8f PH |
131 | .SH ATTRIBUTES |
132 | For an explanation of the terms used in this section, see | |
133 | .BR attributes (7). | |
134 | .TS | |
135 | allbox; | |
136 | lb lb lb | |
137 | l l l. | |
138 | Interface Attribute Value | |
139 | T{ | |
140 | .BR inet_pton () | |
141 | T} Thread safety MT-Safe locale | |
142 | .TE | |
47297adb | 143 | .SH CONFORMING TO |
9d47ddf3 | 144 | POSIX.1-2001, POSIX.1-2008. |
cd1aabe6 MK |
145 | .SH NOTES |
146 | Unlike | |
147 | .BR inet_aton (3) | |
148 | and | |
149 | .BR inet_addr (3), | |
150 | .BR inet_pton () | |
151 | supports IPv6 addresses. | |
152 | On the other hand, | |
153 | .BR inet_pton () | |
33a0ccb2 | 154 | accepts only IPv4 addresses in dotted-decimal notation, whereas |
cd1aabe6 MK |
155 | .BR inet_aton (3) |
156 | and | |
157 | .BR inet_addr (3) | |
158 | allow the more general numbers-and-dots notation (hexadecimal | |
159 | and octal number formats, and formats that don't require all | |
160 | four bytes to be explicitly written). | |
161 | For an interface that handles both IPv6 addresses, and IPv4 | |
162 | addresses in numbers-and-dots notation, see | |
163 | .BR getaddrinfo (3). | |
25768803 MK |
164 | .SH BUGS |
165 | .B AF_INET6 | |
166 | does not recognize IPv4 addresses. | |
167 | An explicit IPv4-mapped IPv6 address must be supplied in | |
168 | .I src | |
169 | instead. | |
cd1aabe6 MK |
170 | .SH EXAMPLE |
171 | The program below demonstrates the use of | |
172 | .BR inet_pton () | |
173 | and | |
174 | .BR inet_ntop (3). | |
175 | Here are some example runs: | |
e646a1ba | 176 | .PP |
cd1aabe6 | 177 | .in +4n |
e646a1ba | 178 | .EX |
b43a3b30 | 179 | .RB "$" " ./a.out i6 0:0:0:0:0:0:0:0" |
cd1aabe6 | 180 | :: |
b43a3b30 | 181 | .RB "$" " ./a.out i6 1:0:0:0:0:0:0:8" |
cd1aabe6 | 182 | 1::8 |
b43a3b30 | 183 | .RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116" |
cd1aabe6 | 184 | ::ffff:204.152.189.116 |
b8302363 | 185 | .EE |
cd1aabe6 | 186 | .in |
9c330504 | 187 | .SS Program source |
d84d0300 | 188 | \& |
e7d0bb47 | 189 | .EX |
cd1aabe6 MK |
190 | #include <arpa/inet.h> |
191 | #include <stdio.h> | |
192 | #include <stdlib.h> | |
193 | #include <string.h> | |
194 | ||
195 | int | |
196 | main(int argc, char *argv[]) | |
197 | { | |
198 | unsigned char buf[sizeof(struct in6_addr)]; | |
199 | int domain, s; | |
200 | char str[INET6_ADDRSTRLEN]; | |
201 | ||
202 | if (argc != 3) { | |
203 | fprintf(stderr, "Usage: %s {i4|i6|<num>} string\\n", argv[0]); | |
204 | exit(EXIT_FAILURE); | |
205 | } | |
206 | ||
207 | domain = (strcmp(argv[1], "i4") == 0) ? AF_INET : | |
208 | (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]); | |
209 | ||
210 | s = inet_pton(domain, argv[2], buf); | |
211 | if (s <= 0) { | |
212 | if (s == 0) | |
213 | fprintf(stderr, "Not in presentation format"); | |
214 | else | |
215 | perror("inet_pton"); | |
216 | exit(EXIT_FAILURE); | |
217 | } | |
218 | ||
219 | if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) { | |
220 | perror("inet_ntop"); | |
221 | exit(EXIT_FAILURE); | |
cd60dedd | 222 | } |
cd1aabe6 MK |
223 | |
224 | printf("%s\\n", str); | |
225 | ||
226 | exit(EXIT_SUCCESS); | |
227 | } | |
e7d0bb47 | 228 | .EE |
47297adb | 229 | .SH SEE ALSO |
cd1aabe6 MK |
230 | .BR getaddrinfo (3), |
231 | .BR inet (3), | |
e37e3282 | 232 | .BR inet_ntop (3) |