Debian Codegraph @

upstream/debian-trixie/man3/inet_pton.3

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