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