man3/inet_pton.3

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