man3/inet.3

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   4 .\"
   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 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\"     libc.info (from glibc distribution)
  30 .\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith <faith@cs.unc.edu>
  31 .\" Modified Sun Sep  3 20:29:36 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
  32 .\" Changed network into host byte order (for inet_network),
  33 .\"     Andreas Jaeger <aj@arthur.rhein-neckar.de>, 980130.
  34 .\"
  35 .TH INET 3  2007-07-26 "GNU" "Linux Programmer's Manual"
  36 .SH NAME
  37 inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof,
  38 inet_netof \- Internet address manipulation routines
  39 .SH SYNOPSIS
  40 .nf
  41 .B #include <sys/socket.h>
  42 .B #include <netinet/in.h>
  43 .B #include <arpa/inet.h>
  44 .sp
  45 .BI "int inet_aton(const char *" cp ", struct in_addr *" inp );
  46 .sp
  47 .BI "in_addr_t inet_addr(const char *" cp );
  48 .sp
  49 .BI "in_addr_t inet_network(const char *" cp );
  50 .sp
  51 .BI "char *inet_ntoa(struct in_addr " in );
  52 .sp
  53 .BI "struct in_addr inet_makeaddr(int " net ", int " host );
  54 .sp
  55 .BI "in_addr_t inet_lnaof(struct in_addr " in );
  56 .sp
  57 .BI "in_addr_t inet_netof(struct in_addr " in );
  58 .fi
  59 .sp
  60 .in -4n
  61 Feature Test Macro Requirements for glibc (see
  62 .BR feature_test_macros (7)):
  63 .in
  64 .sp
  65 .BR inet_aton (),
  66 .BR inet_ntoa ():
  67 _BSD_SOURCE || _SVID_SOURCE
  68 .SH DESCRIPTION
  69 .BR inet_aton ()
  70 converts the Internet host address \fIcp\fP from the
  71 standard numbers-and-dots notation into binary data and stores it in
  72 the structure that \fIinp\fP points to.
  73 .BR inet_aton ()
  74 returns
  75 nonzero if the address is valid, zero if not.
  76 .PP
  77 The
  78 .BR inet_addr ()
  79 function converts the Internet host address
  80 \fIcp\fP from numbers-and-dots notation into binary data in network
  81 byte order.
  82 If the input is invalid,
  83 .B INADDR_NONE
  84 (usually \-1) is returned.
  85 This is an \fIobsolete\fP interface to
  86 .BR inet_aton (),
  87 described
  88 immediately above; it is obsolete because \-1 is a valid address
  89 (255.255.255.255), and
  90 .BR inet_aton ()
  91 provides a cleaner way
  92 to indicate error return.
  93 .PP
  94 The
  95 .BR inet_network ()
  96 function extracts
  97 a number in host byte order suitable for use as an Internet address
  98 from \fIcp\fP, which is a string in numbers-and-dots notation.
  99 If the input is invalid, \-1 is returned.
 100 .PP
 101 The
 102 .BR inet_ntoa ()
 103 function converts the Internet host address
 104 \fIin\fP given in network byte order to a string in standard
 105 numbers-and-dots notation.
 106 The string is returned in a statically
 107 allocated buffer, which subsequent calls will overwrite.
 108 .PP
 109 The
 110 .BR inet_makeaddr ()
 111 function makes an Internet host address
 112 in network byte order by combining the network number \fInet\fP
 113 with the local address \fIhost\fP in network \fInet\fP, both in
 114 local host byte order.
 115 .PP
 116 The
 117 .BR inet_lnaof ()
 118 function returns the local host address part
 119 of the Internet address \fIin\fP.
 120 The local host address is returned
 121 in local host byte order.
 122 .PP
 123 The
 124 .BR inet_netof ()
 125 function returns the network number part of
 126 the Internet Address \fIin\fP.
 127 The network number is returned in
 128 local host byte order.
 129 .PP
 130 The structure \fIin_addr\fP as used in
 131 .BR inet_ntoa (),
 132 .BR inet_makeaddr (),
 133 .BR inet_lnaof ()
 134 and
 135 .BR inet_netof ()
 136 is defined in
 137 .I <netinet/in.h>
 138 as:
 139 .sp
 140 .in +4n
 141 .nf
 142 typedef uint32_t in_addr_t;
 143
 144 struct in_addr {
 145     in_addr_t s_addr;
 146 };
 147 .fi
 148 .in
 149 .PP
 150 Note that on the i386 the host byte order is Least Significant Byte
 151 first (little endian), whereas the network byte order, as used on the
 152 Internet, is Most Significant Byte first (big endian).
 153 .SH "CONFORMING TO"
 154 4.3BSD.
 155 .BR inet_addr (),
 156 .BR inet_aton (),
 157 and
 158 .BR inet_ntoa ()
 159 are specified in POSIX.1-2001.
 160 .SH NOTES
 161 When you using numbers-and-dots notation for addresses,
 162 be aware that each number will be interpreted as octal
 163 if preceded by a 0 and as hexadecimal if preceded by 0x.
 164 For example, \fBinet_aton("226.000.000.037", &t)\fP will
 165 interpret the address as \fI226.0.0.31\fP and not \fI226.0.0.37\fP.
 166 .SH "SEE ALSO"
 167 .BR gethostbyname (3),
 168 .BR getnetent (3),
 169 .BR inet_ntop (3),
 170 .BR inet_pton (3),
 171 .BR hosts (5),
 172 .BR networks (5)