man3/inet.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
   3 .\"     <mtk.manpages@gmail.com>
   4 .\"
   5 .\" %%%LICENSE_START(VERBATIM)
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\" %%%LICENSE_END
  26 .\"
  27 .\" References consulted:
  28 .\"     Linux libc source code
  29 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  30 .\"     386BSD man pages
  31 .\"     libc.info (from glibc distribution)
  32 .\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith <faith@cs.unc.edu>
  33 .\" Modified Sun Sep  3 20:29:36 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
  34 .\" Changed network into host byte order (for inet_network),
  35 .\"     Andreas Jaeger <aj@arthur.rhein-neckar.de>, 980130.
  36 .\" 2008-06-19, mtk
  37 .\"     Describe the various address forms supported by inet_aton().
  38 .\"     Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr().
  39 .\"     Add discussion of Classful Addressing, noting that it is obsolete.
  40 .\"     Added an EXAMPLE program.
  41 .\"
  42 .TH INET 3  2021-03-22 "GNU" "Linux Programmer's Manual"
  43 .SH NAME
  44 inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof,
  45 inet_netof \- Internet address manipulation routines
  46 .SH SYNOPSIS
  47 .nf
  48 .B #include <sys/socket.h>
  49 .B #include <netinet/in.h>
  50 .B #include <arpa/inet.h>
  51 .PP
  52 .BI "int inet_aton(const char *" cp ", struct in_addr *" inp );
  53 .PP
  54 .BI "in_addr_t inet_addr(const char *" cp );
  55 .BI "in_addr_t inet_network(const char *" cp );
  56 .PP
  57 .BI "char *inet_ntoa(struct in_addr " in );
  58 .PP
  59 .BI "struct in_addr inet_makeaddr(in_addr_t " net ", in_addr_t " host );
  60 .PP
  61 .BI "in_addr_t inet_lnaof(struct in_addr " in );
  62 .BI "in_addr_t inet_netof(struct in_addr " in );
  63 .fi
  64 .PP
  65 .RS -4
  66 Feature Test Macro Requirements for glibc (see
  67 .BR feature_test_macros (7)):
  68 .RE
  69 .PP
  70 .BR inet_aton (),
  71 .BR inet_ntoa ():
  72 .nf
  73     Since glibc 2.19:
  74         _DEFAULT_SOURCE
  75     In glibc up to and including 2.19:
  76         _BSD_SOURCE || _BSD_SOURCE
  77 .fi
  78 .SH DESCRIPTION
  79 .BR inet_aton ()
  80 converts the Internet host address \fIcp\fP from the
  81 IPv4 numbers-and-dots notation into binary form (in network byte order)
  82 and stores it in the structure that \fIinp\fP points to.
  83 .BR inet_aton ()
  84 returns nonzero if the address is valid, zero if not.
  85 The address supplied in
  86 .I cp
  87 can have one of the following forms:
  88 .TP 10
  89 .I a.b.c.d
  90 Each of the four numeric parts specifies a byte of the address;
  91 the bytes are assigned in left-to-right order to produce the binary address.
  92 .TP
  93 .I a.b.c
  94 Parts
  95 .I a
  96 and
  97 .I b
  98 specify the first two bytes of the binary address.
  99 Part
 100 .I c
 101 is interpreted as a 16-bit value that defines the rightmost two bytes
 102 of the binary address.
 103 This notation is suitable for specifying (outmoded) Class B
 104 network addresses.
 105 .TP
 106 .I a.b
 107 Part
 108 .I a
 109 specifies the first byte of the binary address.
 110 Part
 111 .I b
 112 is interpreted as a 24-bit value that defines the rightmost three bytes
 113 of the binary address.
 114 This notation is suitable for specifying (outmoded) Class A
 115 network addresses.
 116 .TP
 117 .I a
 118 The value
 119 .I a
 120 is interpreted as a 32-bit value that is stored directly
 121 into the binary address without any byte rearrangement.
 122 .PP
 123 In all of the above forms,
 124 components of the dotted address can be specified in decimal,
 125 octal (with a leading
 126 .IR 0 ),
 127 or hexadecimal, with a leading
 128 .IR 0X ).
 129 Addresses in any of these forms are collectively termed
 130 .IR "IPV4 numbers-and-dots notation" .
 131 The form that uses exactly four decimal numbers is referred to as
 132 .IR "IPv4 dotted-decimal notation"
 133 (or sometimes:
 134 .IR "IPv4 dotted-quad notation" ).
 135 .PP
 136 .BR inet_aton ()
 137 returns 1 if the supplied string was successfully interpreted,
 138 or 0 if the string is invalid
 139 .RB ( errno
 140 is
 141 .I not
 142 set on error).
 143 .PP
 144 The
 145 .BR inet_addr ()
 146 function converts the Internet host address
 147 \fIcp\fP from IPv4 numbers-and-dots notation into binary data in network
 148 byte order.
 149 If the input is invalid,
 150 .B INADDR_NONE
 151 (usually \-1) is returned.
 152 Use of this function is problematic because \-1 is a valid address
 153 (255.255.255.255).
 154 Avoid its use in favor of
 155 .BR inet_aton (),
 156 .BR inet_pton (3),
 157 or
 158 .BR getaddrinfo (3),
 159 which provide a cleaner way to indicate error return.
 160 .PP
 161 The
 162 .BR inet_network ()
 163 function converts
 164 .IR cp ,
 165 a string in IPv4 numbers-and-dots notation,
 166 into a number in host byte order suitable for use as an
 167 Internet network address.
 168 On success, the converted address is returned.
 169 If the input is invalid, \-1 is returned.
 170 .PP
 171 The
 172 .BR inet_ntoa ()
 173 function converts the Internet host address
 174 \fIin\fP, given in network byte order, to a string in IPv4
 175 dotted-decimal notation.
 176 The string is returned in a statically
 177 allocated buffer, which subsequent calls will overwrite.
 178 .PP
 179 The
 180 .BR inet_lnaof ()
 181 function returns the local network address part
 182 of the Internet address \fIin\fP.
 183 The returned value is in host byte order.
 184 .PP
 185 The
 186 .BR inet_netof ()
 187 function returns the network number part of
 188 the Internet address \fIin\fP.
 189 The returned value is in host byte order.
 190 .PP
 191 The
 192 .BR inet_makeaddr ()
 193 function is the converse of
 194 .BR inet_netof ()
 195 and
 196 .BR inet_lnaof ().
 197 It returns an Internet host address in network byte order,
 198 created by combining the network number \fInet\fP
 199 with the local address \fIhost\fP, both in
 200 host byte order.
 201 .PP
 202 The structure \fIin_addr\fP as used in
 203 .BR inet_ntoa (),
 204 .BR inet_makeaddr (),
 205 .BR inet_lnaof (),
 206 and
 207 .BR inet_netof ()
 208 is defined in
 209 .I <netinet/in.h>
 210 as:
 211 .PP
 212 .in +4n
 213 .EX
 214 typedef uint32_t in_addr_t;
 215
 216 struct in_addr {
 217     in_addr_t s_addr;
 218 };
 219 .EE
 220 .in
 221 .SH ATTRIBUTES
 222 For an explanation of the terms used in this section, see
 223 .BR attributes (7).
 224 .ad l
 225 .nh
 226 .TS
 227 allbox;
 228 lbx lb lb
 229 l l l.
 230 Interface       Attribute       Value
 231 T{
 232 .BR inet_aton (),
 233 .BR inet_addr (),
 234 .BR inet_network (),
 235 .BR inet_ntoa ()
 236 T}      Thread safety   MT-Safe locale
 237 T{
 238 .BR inet_makeaddr (),
 239 .BR inet_lnaof (),
 240 .BR inet_netof ()
 241 T}      Thread safety   MT-Safe
 242 .TE
 243 .hy
 244 .ad
 245 .sp 1
 246 .SH CONFORMING TO
 247 .BR inet_addr (),
 248 .BR inet_ntoa ():
 249 POSIX.1-2001, POSIX.1-2008, 4.3BSD.
 250 .PP
 251 .BR inet_aton ()
 252 is not specified in POSIX.1, but is available on most systems.
 253 .SH NOTES
 254 On x86 architectures, the host byte order is Least Significant Byte
 255 first (little endian), whereas the network byte order, as used on the
 256 Internet, is Most Significant Byte first (big endian).
 257 .PP
 258 .BR inet_lnaof (),
 259 .BR inet_netof (),
 260 and
 261 .BR inet_makeaddr ()
 262 are legacy functions that assume they are dealing with
 263 .IR "classful network addresses" .
 264 Classful networking divides IPv4 network addresses into host and network
 265 components at byte boundaries, as follows:
 266 .TP 10
 267 Class A
 268 This address type is indicated by the value 0 in the
 269 most significant bit of the (network byte ordered) address.
 270 The network address is contained in the most significant byte,
 271 and the host address occupies the remaining three bytes.
 272 .TP
 273 Class B
 274 This address type is indicated by the binary value 10 in the
 275 most significant two bits of the address.
 276 The network address is contained in the two most significant bytes,
 277 and the host address occupies the remaining two bytes.
 278 .TP
 279 Class C
 280 This address type is indicated by the binary value 110 in the
 281 most significant three bits of the address.
 282 The network address is contained in the three most significant bytes,
 283 and the host address occupies the remaining byte.
 284 .PP
 285 Classful network addresses are now obsolete,
 286 having been superseded by Classless Inter-Domain Routing (CIDR),
 287 which divides addresses into network and host components at
 288 arbitrary bit (rather than byte) boundaries.
 289 .SH EXAMPLES
 290 An example of the use of
 291 .BR inet_aton ()
 292 and
 293 .BR inet_ntoa ()
 294 is shown below.
 295 Here are some example runs:
 296 .PP
 297 .in +4n
 298 .EX
 299 .RB "$" " ./a.out 226.000.000.037" "      # Last byte is in octal"
 300 226.0.0.31
 301 .RB "$" " ./a.out 0x7f.1         " "      # First byte is in hex"
 302 127.0.0.1
 303 .EE
 304 .in
 305 .SS Program source
 306 \&
 307 .EX
 308 #define _BSD_SOURCE
 309 #include <arpa/inet.h>
 310 #include <stdio.h>
 311 #include <stdlib.h>
 312
 313 int
 314 main(int argc, char *argv[])
 315 {
 316     struct in_addr addr;
 317
 318     if (argc != 2) {
 319         fprintf(stderr, "%s <dotted\-address>\en", argv[0]);
 320         exit(EXIT_FAILURE);
 321     }
 322
 323     if (inet_aton(argv[1], &addr) == 0) {
 324         fprintf(stderr, "Invalid address\en");
 325         exit(EXIT_FAILURE);
 326     }
 327
 328     printf("%s\en", inet_ntoa(addr));
 329     exit(EXIT_SUCCESS);
 330 }
 331 .EE
 332 .SH SEE ALSO
 333 .BR byteorder (3),
 334 .BR getaddrinfo (3),
 335 .BR gethostbyname (3),
 336 .BR getnameinfo (3),
 337 .BR getnetent (3),
 338 .BR inet_net_pton (3),
 339 .BR inet_ntop (3),
 340 .BR inet_pton (3),
 341 .BR hosts (5),
 342 .BR networks (5)