original/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 2008-06-18 "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 CONFORMING TO
 130 POSIX.1-2001.
 131 .SH NOTES
 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 BUGS
 151 .B AF_INET6
 152 does not recognize IPv4 addresses.
 153 An explicit IPv4-mapped IPv6 address must be supplied in
 154 .I src
 155 instead.
 156 .SH EXAMPLE
 157 The program below demonstrates the use of
 158 .BR inet_pton ()
 159 and
 160 .BR inet_ntop (3).
 161 Here are some example runs:
 162 .in +4n
 163 .nf
 164
 165 .RB "$" " ./a.out i6 0:0:0:0:0:0:0:0"
 166 ::
 167 .RB "$" " ./a.out i6 1:0:0:0:0:0:0:8"
 168 1::8
 169 .RB "$" " ./a.out i6 0:0:0:0:0:FFFF:204.152.189.116"
 170 ::ffff:204.152.189.116
 171 .fi
 172 .in
 173 .SS Program source
 174 \&
 175 .nf
 176 #include <arpa/inet.h>
 177 #include <stdio.h>
 178 #include <stdlib.h>
 179 #include <string.h>
 180
 181 int
 182 main(int argc, char *argv[])
 183 {
 184     unsigned char buf[sizeof(struct in6_addr)];
 185     int domain, s;
 186     char str[INET6_ADDRSTRLEN];
 187
 188     if (argc != 3) {
 189         fprintf(stderr, "Usage: %s {i4|i6|<num>} string\\n", argv[0]);
 190         exit(EXIT_FAILURE);
 191     }
 192
 193     domain = (strcmp(argv[1], "i4") == 0) ? AF_INET :
 194              (strcmp(argv[1], "i6") == 0) ? AF_INET6 : atoi(argv[1]);
 195
 196     s = inet_pton(domain, argv[2], buf);
 197     if (s <= 0) {
 198         if (s == 0)
 199             fprintf(stderr, "Not in presentation format");
 200         else
 201             perror("inet_pton");
 202         exit(EXIT_FAILURE);
 203     }
 204
 205     if (inet_ntop(domain, buf, str, INET6_ADDRSTRLEN) == NULL) {
 206         perror("inet_ntop");
 207         exit(EXIT_FAILURE);
 208     }
 209
 210     printf("%s\\n", str);
 211
 212     exit(EXIT_SUCCESS);
 213 }
 214 .fi
 215 .SH SEE ALSO
 216 .BR getaddrinfo (3),
 217 .BR inet (3),
 218 .BR inet_ntop (3)
 219 .SH COLOPHON
 220 This page is part of release 3.65 of the Linux
 221 .I man-pages
 222 project.
 223 A description of the project,
 224 and information about reporting bugs,
 225 can be found at
 226 \%http://www.kernel.org/doc/man\-pages/.