Debian Codegraph @

upstream/debian-unstable/man3/inet_pton.3

raw
1 '\" t
2 .\" Copyright 2008, Michael Kerrisk <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH inet_pton 3 2026-02-22 "Linux man-pages 6.18"
8 .SH NAME
9 inet_pton \- convert IPv4 and IPv6 addresses from text to binary form
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <arpa/inet.h>
16 .P
17 .BI "int inet_pton(int " af ", const char *restrict " src \
18 ", void *restrict " dst );
19 .fi
20 .SH DESCRIPTION
21 This function converts the character string
22 .I src
23 into a network address structure in the
24 .I af
25 address family, then
26 copies
27 the network address structure to
28 .IR dst .
29 The
30 .I af
31 argument must be either
32 .B AF_INET
33 or
34 .BR AF_INET6 .
35 .I dst
36 is written in network byte order.
37 .P
38 The following address families are currently supported:
39 .TP
40 .B AF_INET
41 .I src
42 points to a character string containing an IPv4 network address in
43 dotted-decimal format,
44 .RI \[dq] ddd.ddd.ddd.ddd \[dq],
45 where
46 .I ddd
47 is a decimal number of up to three digits in the range 0 to 255.
48 The address is converted to a
49 .I struct in_addr
50 and copied to
51 .IR dst ,
52 which must be
53 .I sizeof(struct in_addr)
54 (4) bytes (32 bits) long.
55 .TP
56 .B AF_INET6
57 .I src
58 points to a character string containing an IPv6 network address.
59 The address is converted to a
60 .I struct in6_addr
61 and copied to
62 .IR dst ,
63 which must be
64 .I sizeof(struct in6_addr)
65 (16) bytes (128 bits) long.
66 The allowed formats for IPv6 addresses follow these rules:
67 .RS
68 .IP \[bu] 3
69 The preferred format is
70 .IR x:x:x:x:x:x:x:x .
71 This form consists of eight hexadecimal numbers,
72 each of which expresses a 16-bit value (i.e., each
73 .I x
74 can be up to 4 hex digits).
75 .IP \[bu]
76 A series of contiguous zero values in the preferred format
77 can be abbreviated to
78 .IR :: .
79 Only one instance of
80 .I ::
81 can occur in an address.
82 For example, the loopback address
83 .I 0:0:0:0:0:0:0:1
84 can be abbreviated as
85 .IR ::1 .
86 The wildcard address, consisting of all zeros, can be written as
87 .IR :: .
88 .IP \[bu]
89 An alternate format is useful for expressing IPv4-mapped IPv6 addresses.
90 This form is written as
91 .IR x:x:x:x:x:x:d.d.d.d ,
92 where the six leading
93 .IR x s
94 are hexadecimal values that define the six most-significant
95 16-bit pieces of the address (i.e., 96 bits), and the
96 .IR d s
97 express a value in dotted-decimal notation that
98 defines the least significant 32 bits of the address.
99 An example of such an address is
100 .IR ::FFFF:204.152.189.116 .
101 .RE
102 .IP
103 See RFC 2373 for further details on the representation of IPv6 addresses.
104 .SH RETURN VALUE
105 .BR inet_pton ()
106 returns 1 on success (network address was successfully converted).
107 0 is returned if
108 .I src
109 does not contain a character string representing a valid network
110 address in the specified address family.
111 If
112 .I af
113 does not contain a valid address family, \-1 is returned and
114 .I errno
115 is set to
116 .BR EAFNOSUPPORT .
117 .SH ATTRIBUTES
118 For an explanation of the terms used in this section, see
119 .BR attributes (7).
120 .TS
121 allbox;
122 lbx lb lb
123 l l l.
124 Interface Attribute Value
125 T{
126 .na
127 .nh
128 .BR inet_pton ()
129 T} Thread safety MT-Safe locale
130 .TE
131 .SH VERSIONS
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 accepts only 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 STANDARDS
151 POSIX.1-2008.
152 .SH HISTORY
153 POSIX.1-2001.
154 .SH BUGS
155 .B AF_INET6
156 does not recognize IPv4 addresses.
157 An explicit IPv4-mapped IPv6 address must be supplied in
158 .I src
159 instead.
160 .SH EXAMPLES
161 The program below demonstrates the use of
162 .BR inet_pton ()
163 and
164 .BR inet_ntop (3).
165 Here are some example runs:
166 .P
167 .in +4n
168 .EX
169 .RB "$" " ./a.out i6 0:0:0:0:0:0:0:0"
170 ::
171 .RB "$" " ./a.out i6 1:0:0:0:0:0:0:8"
172 1::8
173 .RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116"
174 ::ffff:204.152.189.116
175 .EE
176 .in
177 .SS Program source
178 \&
179 .\" SRC BEGIN (inet_pton.c)
180 .EX
181 #include <arpa/inet.h>
182 #include <stdio.h>
183 #include <stdlib.h>
184 #include <string.h>
185 \&
186 #define streq(...) (strcmp(__VA_ARGS__) == 0)
187 \&
188 int
189 main(int argc, char *argv[])
190 {
191 unsigned char buf[sizeof(struct in6_addr)];
192 int domain, s;
193 char str[INET6_ADDRSTRLEN];
194 \&
195 if (argc != 3) {
196 fprintf(stderr, "Usage: %s {i4|i6|<num>} string\[rs]n", argv[0]);
197 exit(EXIT_FAILURE);
198 }
199 \&
200 domain = streq(argv[1], "i4") ? AF_INET :
201 streq(argv[1], "i6") ? AF_INET6 : atoi(argv[1]);
202 \&
203 s = inet_pton(domain, argv[2], buf);
204 if (s <= 0) {
205 if (s == 0)
206 fprintf(stderr, "Not in presentation format");
207 else
208 perror("inet_pton");
209 exit(EXIT_FAILURE);
210 }
211 \&
212 if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) {
213 perror("inet_ntop");
214 exit(EXIT_FAILURE);
215 }
216 \&
217 printf("%s\[rs]n", str);
218 \&
219 exit(EXIT_SUCCESS);
220 }
221 .EE
222 .\" SRC END
223 .SH SEE ALSO
224 .BR getaddrinfo (3),
225 .BR inet (3),
226 .BR inet_ntop (3)