original/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  2014-04-19 "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 .sp
  52 .BI "int inet_aton(const char *" cp ", struct in_addr *" inp );
  53 .sp
  54 .BI "in_addr_t inet_addr(const char *" cp );
  55 .sp
  56 .BI "in_addr_t inet_network(const char *" cp );
  57 .sp
  58 .BI "char *inet_ntoa(struct in_addr " in );
  59 .sp
  60 .BI "struct in_addr inet_makeaddr(int " net ", int " host );
  61 .sp
  62 .BI "in_addr_t inet_lnaof(struct in_addr " in );
  63 .sp
  64 .BI "in_addr_t inet_netof(struct in_addr " in );
  65 .fi
  66 .sp
  67 .in -4n
  68 Feature Test Macro Requirements for glibc (see
  69 .BR feature_test_macros (7)):
  70 .in
  71 .sp
  72 .BR inet_aton (),
  73 .BR inet_ntoa ():
  74 _BSD_SOURCE || _SVID_SOURCE
  75 .SH DESCRIPTION
  76 .BR inet_aton ()
  77 converts the Internet host address \fIcp\fP from the
  78 IPv4 numbers-and-dots notation into binary form (in network byte order)
  79 and stores it in the structure that \fIinp\fP points to.
  80 .BR inet_aton ()
  81 returns nonzero if the address is valid, zero if not.
  82 The address supplied in
  83 .I cp
  84 can have one of the following forms:
  85 .TP 10
  86 .I a.b.c.d
  87 Each of the four numeric parts specifies a byte of the address;
  88 the bytes are assigned in left-to-right order to produce the binary address.
  89 .TP
  90 .I a.b.c
  91 Parts
  92 .I a
  93 and
  94 .I b
  95 specify the first two bytes of the binary address.
  96 Part
  97 .I c
  98 is interpreted as a 16-bit value that defines the rightmost two bytes
  99 of the binary address.
 100 This notation is suitable for specifying (outmoded) Class B
 101 network addresses.
 102 .TP
 103 .I a.b
 104 Part
 105 .I a
 106 specifies the first byte of the binary address.
 107 Part
 108 .I b
 109 is interpreted as a 24-bit value that defines the rightmost three bytes
 110 of the binary address.
 111 This notation is suitable for specifying (outmoded) Class A
 112 network addresses.
 113 .TP
 114 .I a
 115 The value
 116 .I a
 117 is interpreted as a 32-bit value that is stored directly
 118 into the binary address without any byte rearrangement.
 119 .PP
 120 In all of the above forms,
 121 components of the dotted address can be specified in decimal,
 122 octal (with a leading
 123 .IR 0 ),
 124 or hexadecimal, with a leading
 125 .IR 0X ).
 126 Addresses in any of these forms are collectively termed
 127 .IR "IPV4 numbers-and-dots notation" .
 128 The form that uses exactly four decimal numbers is referred to as
 129 .IR "IPv4 dotted-decimal notation"
 130 (or sometimes:
 131 .IR "IPv4 dotted-quad notation" ).
 132
 133 If
 134 .BR inet_aton ()
 135 returns 1 if the supplied string was successfully interpreted,
 136 or 0 if the string is invalid
 137 .RB ( errno
 138 is
 139 .I not
 140 set on error).
 141 .PP
 142 The
 143 .BR inet_addr ()
 144 function converts the Internet host address
 145 \fIcp\fP from IPv4 numbers-and-dots notation into binary data in network
 146 byte order.
 147 If the input is invalid,
 148 .B INADDR_NONE
 149 (usually \-1) is returned.
 150 Use of this function is problematic because \-1 is a valid address
 151 (255.255.255.255).
 152 Avoid its use in favor of
 153 .BR inet_aton (),
 154 .BR inet_pton (3),
 155 or
 156 .BR getaddrinfo (3)
 157 which provide a cleaner way to indicate error return.
 158 .PP
 159 The
 160 .BR inet_network ()
 161 function converts
 162 .IR cp ,
 163 a string in IPv4 numbers-and-dots notation,
 164 into a number in host byte order suitable for use as an
 165 Internet network address.
 166 On success, the converted address is returned.
 167 If the input is invalid, \-1 is returned.
 168 .PP
 169 The
 170 .BR inet_ntoa ()
 171 function converts the Internet host address
 172 \fIin\fP, given in network byte order, to a string in IPv4
 173 dotted-decimal notation.
 174 The string is returned in a statically
 175 allocated buffer, which subsequent calls will overwrite.
 176 .PP
 177 The
 178 .BR inet_lnaof ()
 179 function returns the local network address part
 180 of the Internet address \fIin\fP.
 181 The returned value is in host byte order.
 182 .PP
 183 The
 184 .BR inet_netof ()
 185 function returns the network number part of
 186 the Internet address \fIin\fP.
 187 The returned value is in host byte order.
 188 .PP
 189 The
 190 .BR inet_makeaddr ()
 191 function is the converse of
 192 .BR inet_netof ()
 193 and
 194 .BR inet_lnaof ().
 195 It returns an Internet host address in network byte order,
 196 created by combining the network number \fInet\fP
 197 with the local address \fIhost\fP, both in
 198 host byte order.
 199 .PP
 200 The structure \fIin_addr\fP as used in
 201 .BR inet_ntoa (),
 202 .BR inet_makeaddr (),
 203 .BR inet_lnaof ()
 204 and
 205 .BR inet_netof ()
 206 is defined in
 207 .I <netinet/in.h>
 208 as:
 209 .sp
 210 .in +4n
 211 .nf
 212 typedef uint32_t in_addr_t;
 213
 214 struct in_addr {
 215     in_addr_t s_addr;
 216 };
 217 .fi
 218 .in
 219 .SH CONFORMING TO
 220 4.3BSD.
 221 .BR inet_addr ()
 222 and
 223 .BR inet_ntoa ()
 224 are specified in POSIX.1-2001.
 225 .BR inet_aton ()
 226 is not specified in POSIX.1-2001, but is available on most systems.
 227 .SH NOTES
 228 On the i386 the host byte order is Least Significant Byte
 229 first (little endian), whereas the network byte order, as used on the
 230 Internet, is Most Significant Byte first (big endian).
 231
 232 .BR inet_lnaof (),
 233 .BR inet_netof (),
 234 and
 235 .BR inet_makeaddr ()
 236 are legacy functions that assume they are dealing with
 237 .IR "classful network addresses" .
 238 Classful networking divides IPv4 network addresses into host and network
 239 components at byte boundaries, as follows:
 240 .TP 10
 241 Class A
 242 This address type is indicated by the value 0 in the
 243 most significant bit of the (network byte ordered) address.
 244 The network address is contained in the most significant byte,
 245 and the host address occupies the remaining three bytes.
 246 .TP
 247 Class B
 248 This address type is indicated by the binary value 10 in the
 249 most significant two bits of the address.
 250 The network address is contained in the two most significant bytes,
 251 and the host address occupies the remaining two bytes.
 252 .TP
 253 Class C
 254 This address type is indicated by the binary value 110 in the
 255 most significant three bits of the address.
 256 The network address is contained in the three most significant bytes,
 257 and the host address occupies the remaining byte.
 258 .PP
 259 Classful network addresses are now obsolete,
 260 having been superseded by Classless Inter-Domain Routing (CIDR),
 261 which divides addresses into network and host components at
 262 arbitrary bit (rather than byte) boundaries.
 263 .SH EXAMPLE
 264 An example of the use of
 265 .BR inet_aton ()
 266 and
 267 .BR inet_ntoa ()
 268 is shown below.
 269 Here are some example runs:
 270 .in +4n
 271 .nf
 272
 273 .RB "$" " ./a.out 226.000.000.037" "      # Last byte is in octal"
 274 226.0.0.31
 275 .RB "$" " ./a.out 0x7f.1         " "      # First byte is in hex"
 276 127.0.0.1
 277 .fi
 278 .in
 279 .SS Program source
 280 \&
 281 .nf
 282 #define _BSD_SOURCE
 283 #include <arpa/inet.h>
 284 #include <stdio.h>
 285 #include <stdlib.h>
 286
 287 int
 288 main(int argc, char *argv[])
 289 {
 290     struct in_addr addr;
 291
 292     if (argc != 2) {
 293         fprintf(stderr, "%s <dotted\-address>\\n", argv[0]);
 294         exit(EXIT_FAILURE);
 295     }
 296
 297     if (inet_aton(argv[1], &addr) == 0) {
 298         fprintf(stderr, "Invalid address\\n");
 299         exit(EXIT_FAILURE);
 300     }
 301
 302     printf("%s\\n", inet_ntoa(addr));
 303     exit(EXIT_SUCCESS);
 304 }
 305 .fi
 306 .SH SEE ALSO
 307 .BR byteorder (3),
 308 .BR getaddrinfo (3),
 309 .BR gethostbyname (3),
 310 .BR getnameinfo (3),
 311 .BR getnetent (3),
 312 .BR inet_net_pton (3),
 313 .BR inet_ntop (3),
 314 .BR inet_pton (3),
 315 .BR hosts (5),
 316 .BR networks (5)
 317 .SH COLOPHON
 318 This page is part of release 3.65 of the Linux
 319 .I man-pages
 320 project.
 321 A description of the project,
 322 and information about reporting bugs,
 323 can be found at
 324 \%http://www.kernel.org/doc/man\-pages/.