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