diff options
| -rw-r--r-- | man3/inet_pton.3 | 178 |
1 files changed, 142 insertions, 36 deletions
diff --git a/man3/inet_pton.3 b/man3/inet_pton.3 index 33216f789a..89e98f2fe3 100644 --- a/man3/inet_pton.3 +++ b/man3/inet_pton.3 @@ -1,4 +1,5 @@ .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com> +.\" and Copyright (c) 2008 Michael Kerrisk <mtk.manpages@gmail.com> .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are @@ -21,13 +22,11 @@ .\" the source, must acknowledge the copyright and authors of this work. .\" .\" References: RFC 2553 -.TH INET_PTON 3 2000-12-18 "Linux" "Linux Programmer's Manual" +.TH INET_PTON 3 2008-06-18 "Linux" "Linux Programmer's Manual" .SH NAME -inet_pton \- Create a network address structure +inet_pton \- convert IPv4 and IPv6 addresses from text to binary form .SH SYNOPSIS .nf -.B #include <sys/types.h> -.B #include <sys/socket.h> .B #include <arpa/inet.h> .BI "int inet_pton(int " "af" ", const char *" "src" ", void *" "dst" ); @@ -41,69 +40,176 @@ address family, then copies the network address structure to .IR dst . +The +.I af +argument must be either +.B AF_INET +or +.BR AF_INET6 . .PP -.BR inet_pton () -extends the -.BR inet_addr (3) -function to support multiple address families, -.BR inet_addr (3) -is now considered to be deprecated in favor of -.BR inet_pton (). The following address families are currently supported: .TP .B AF_INET .I src points to a character string containing an IPv4 network address in -the dotted-quad format, "\fIddd.ddd.ddd.ddd\fP". -The address is converted -to a +dotted-decimal format, "\fIddd.ddd.ddd.ddd\fP", where +.I ddd +is a decimal number of up to three digits in the range 0 to 255. +The address is converted to a .I struct in_addr and copied to .IR dst , which must be .I sizeof(struct in_addr) -bytes long. +(4) bytes (32 bits) long. .TP .B AF_INET6 .I src -points to a character string containing an IPv6 network address in -any allowed IPv6 address format. -The address is converted -to a +points to a character string containing an IPv6 network address. +The address is converted to a .I struct in6_addr and copied to .IR dst , which must be .I sizeof(struct in6_addr) -bytes long. -.PP -Certain legacy hex and octal formats of -.B AF_INET -addresses are not supported by -.BR inet_pton (), -which rejects them. +(16) bytes (128 bits) long. +The allowed formats for IPv6 addresses follow these rules: +.RS +.IP 1. 3 +The preferred format is +.IR x.x.x.x.x.x.x.x . +This form consists of eight hexadecimal numbers, +each of which expresses a 16-bit value (i.e., each +.I x +can be up to 4 hex digits). +.IP 2. +A series of contiguous zero values in the preferred format +can be abbreviated to +.IR :: . +Only one instance of +.I :: +can occur in an address. +For example, the loopback address +.I 0:0:0:0:0:0:0:1 +can be abbreviated as +.IR ::1 . +The wildcard address, consisting of all zeroes, can be written as +.IR :: . +.IP 3. +An alternate format is useful for expressing IPv4-mapped IPv6 addresses. +This form is written as +.IR x:x:x:x:x:x:d.d.d.d , +where the six leading +.IR x s +are hexadecimal values that define the six most-significant +16-bit pieces of the address (i.e., 96 bits), and the +.IR d s +express a value in dotted-decimal notation that +defines the least significant 32 bits of the address. +An example of such an address is +.IR ::FFFF:204.152.189.116 . +.RE +.IP +See RFC 2373 for further details on the representation of IPv6 addresses. .SH "RETURN VALUE" .BR inet_pton () -returns a negative value and sets -.I errno -to -.B EAFNOSUPPORT -if -.I af -does not contain a valid address family. +returns 1 on success (network address was successfully converted). 0 is returned if .I src does not contain a character string representing a valid network address in the specified address family. -A positive value is returned if the network address was successfully -converted. +If +.I af +does not contain a valid address family, \-1 is returned and +.I errno +is set to +.BR EAFNOSUPPORT . .SH "CONFORMING TO" POSIX.1-2001. .SH BUGS .B AF_INET6 does not recognize IPv4 addresses. -An explicit IPv6-mapped IPv4 address must be supplied in +An explicit IPv4-mapped IPv6 address must be supplied in .I src instead. +.SH NOTES +Unlike +.BR inet_aton (3) +and +.BR inet_addr (3), +.BR inet_pton () +supports IPv6 addresses. +On the other hand, +.BR inet_pton () +only accepts IPv4 addresses in dotted-decimal notation, whereas +.BR inet_aton (3) +and +.BR inet_addr (3) +allow the more general numbers-and-dots notation (hexadecimal +and octal number formats, and formats that don't require all +four bytes to be explicitly written). +For an interface that handles both IPv6 addresses, and IPv4 +addresses in numbers-and-dots notation, see +.BR getaddrinfo (3). +.SH EXAMPLE +The program below demonstrates the use of +.BR inet_pton () +and +.BR inet_ntop (3). +Here are some example runs: +.in +4n +.nf + +$ ./a.out i6 0:0:0:0:0:0:0:0 +:: +$ ./a.out i6 1:0:0:0:0:0:0:8 +1::8 +$ ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116 +::ffff:204.152.189.116 + +.fi +.in +.nf +#include <arpa/inet.h> +#include <stdio.h> +#include <stdlib.h> +#include <string.h> + +int +main(int argc, char *argv[]) +{ + unsigned char buf[sizeof(struct in6_addr)]; + int domain, s; + char str[INET6_ADDRSTRLEN]; + + if (argc != 3) { + fprintf(stderr, "Usage: %s {i4|i6|<num>} string\\n", argv[0]); + exit(EXIT_FAILURE); + } + + domain = (strcmp(argv[1], "i4") == 0) ? AF_INET : + (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]); + + s = inet_pton(domain, argv[2], buf); + if (s <= 0) { + if (s == 0) + fprintf(stderr, "Not in presentation format"); + else + perror("inet_pton"); + exit(EXIT_FAILURE); + } + + if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) { + perror("inet_ntop"); + exit(EXIT_FAILURE); + } + + printf("%s\\n", str); + + exit(EXIT_SUCCESS); +} +.fi .SH "SEE ALSO" +.BR getaddrinfo (3), +.BR inet (3), .BR inet_ntop (3) |