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