man3/inet_pton.3

   1 '\" t
   2 .\" Copyright 2000 Sam Varshavchik <mrsam@courier-mta.com>
   3 .\" and Copyright (c) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" References: RFC 2553
   8 .TH inet_pton 3 (date) "Linux man-pages (unreleased)"
   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 .PP
  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 .PP
  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 .sp 1
 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 .PP
 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 int
 187 main(int argc, char *argv[])
 188 {
 189     unsigned char buf[sizeof(struct in6_addr)];
 190     int domain, s;
 191     char str[INET6_ADDRSTRLEN];
 192 \&
 193     if (argc != 3) {
 194         fprintf(stderr, "Usage: %s {i4|i6|<num>} string\en", argv[0]);
 195         exit(EXIT_FAILURE);
 196     }
 197 \&
 198     domain = (strcmp(argv[1], "i4") == 0) ? AF_INET :
 199              (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]);
 200 \&
 201     s = inet_pton(domain, argv[2], buf);
 202     if (s <= 0) {
 203         if (s == 0)
 204             fprintf(stderr, "Not in presentation format");
 205         else
 206             perror("inet_pton");
 207         exit(EXIT_FAILURE);
 208     }
 209 \&
 210     if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) {
 211         perror("inet_ntop");
 212         exit(EXIT_FAILURE);
 213     }
 214 \&
 215     printf("%s\en", str);
 216 \&
 217     exit(EXIT_SUCCESS);
 218 }
 219 .EE
 220 .\" SRC END
 221 .SH SEE ALSO
 222 .BR getaddrinfo (3),
 223 .BR inet (3),
 224 .BR inet_ntop (3)