]>
Commit | Line | Data |
---|---|---|
1 | .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> | |
2 | .\" and Copyright (c) 2008 Michael Kerrisk <mtk.manpages@gmail.com> | |
3 | .\" | |
4 | .\" %%%LICENSE_START(VERBATIM) | |
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. | |
13 | .\" | |
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. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" %%%LICENSE_END | |
25 | .\" | |
26 | .\" References: RFC 2553 | |
27 | .TH INET_PTON 3 2008-06-18 "Linux" "Linux Programmer's Manual" | |
28 | .SH NAME | |
29 | inet_pton \- convert IPv4 and IPv6 addresses from text to binary form | |
30 | .SH SYNOPSIS | |
31 | .nf | |
32 | .B #include <arpa/inet.h> | |
33 | ||
34 | .BI "int inet_pton(int " "af" ", const char *" "src" ", void *" "dst" ); | |
35 | .fi | |
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 . | |
45 | The | |
46 | .I af | |
47 | argument must be either | |
48 | .B AF_INET | |
49 | or | |
50 | .BR AF_INET6 . | |
51 | .PP | |
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 | |
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 | |
61 | .I struct in_addr | |
62 | and copied to | |
63 | .IR dst , | |
64 | which must be | |
65 | .I sizeof(struct in_addr) | |
66 | (4) bytes (32 bits) long. | |
67 | .TP | |
68 | .B AF_INET6 | |
69 | .I src | |
70 | points to a character string containing an IPv6 network address. | |
71 | The address is converted to a | |
72 | .I struct in6_addr | |
73 | and copied to | |
74 | .IR dst , | |
75 | which must be | |
76 | .I sizeof(struct in6_addr) | |
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 | |
82 | .IR x:x:x:x:x:x:x:x . | |
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 . | |
98 | The wildcard address, consisting of all zeros, can be written as | |
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. | |
116 | .SH RETURN VALUE | |
117 | .BR inet_pton () | |
118 | returns 1 on success (network address was successfully converted). | |
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. | |
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 . | |
129 | .SH CONFORMING TO | |
130 | POSIX.1-2001. | |
131 | .SH NOTES | |
132 | Unlike | |
133 | .BR inet_aton (3) | |
134 | and | |
135 | .BR inet_addr (3), | |
136 | .BR inet_pton () | |
137 | supports IPv6 addresses. | |
138 | On the other hand, | |
139 | .BR inet_pton () | |
140 | only accepts IPv4 addresses in dotted-decimal notation, whereas | |
141 | .BR inet_aton (3) | |
142 | and | |
143 | .BR inet_addr (3) | |
144 | allow the more general numbers-and-dots notation (hexadecimal | |
145 | and octal number formats, and formats that don't require all | |
146 | four bytes to be explicitly written). | |
147 | For an interface that handles both IPv6 addresses, and IPv4 | |
148 | addresses in numbers-and-dots notation, see | |
149 | .BR getaddrinfo (3). | |
150 | .SH BUGS | |
151 | .B AF_INET6 | |
152 | does not recognize IPv4 addresses. | |
153 | An explicit IPv4-mapped IPv6 address must be supplied in | |
154 | .I src | |
155 | instead. | |
156 | .SH EXAMPLE | |
157 | The program below demonstrates the use of | |
158 | .BR inet_pton () | |
159 | and | |
160 | .BR inet_ntop (3). | |
161 | Here are some example runs: | |
162 | .in +4n | |
163 | .nf | |
164 | ||
165 | .RB "$" " ./a.out i6 0:0:0:0:0:0:0:0" | |
166 | :: | |
167 | .RB "$" " ./a.out i6 1:0:0:0:0:0:0:8" | |
168 | 1::8 | |
169 | .RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116" | |
170 | ::ffff:204.152.189.116 | |
171 | .fi | |
172 | .in | |
173 | .SS Program source | |
174 | \& | |
175 | .nf | |
176 | #include <arpa/inet.h> | |
177 | #include <stdio.h> | |
178 | #include <stdlib.h> | |
179 | #include <string.h> | |
180 | ||
181 | int | |
182 | main(int argc, char *argv[]) | |
183 | { | |
184 | unsigned char buf[sizeof(struct in6_addr)]; | |
185 | int domain, s; | |
186 | char str[INET6_ADDRSTRLEN]; | |
187 | ||
188 | if (argc != 3) { | |
189 | fprintf(stderr, "Usage: %s {i4|i6|<num>} string\\n", argv[0]); | |
190 | exit(EXIT_FAILURE); | |
191 | } | |
192 | ||
193 | domain = (strcmp(argv[1], "i4") == 0) ? AF_INET : | |
194 | (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]); | |
195 | ||
196 | s = inet_pton(domain, argv[2], buf); | |
197 | if (s <= 0) { | |
198 | if (s == 0) | |
199 | fprintf(stderr, "Not in presentation format"); | |
200 | else | |
201 | perror("inet_pton"); | |
202 | exit(EXIT_FAILURE); | |
203 | } | |
204 | ||
205 | if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) { | |
206 | perror("inet_ntop"); | |
207 | exit(EXIT_FAILURE); | |
208 | } | |
209 | ||
210 | printf("%s\\n", str); | |
211 | ||
212 | exit(EXIT_SUCCESS); | |
213 | } | |
214 | .fi | |
215 | .SH SEE ALSO | |
216 | .BR getaddrinfo (3), | |
217 | .BR inet (3), | |
218 | .BR inet_ntop (3) |