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