doc/html/ref/net-common-tcpip-manpages-inet.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >inet</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="TCP/IP Library Reference"
  23 HREF="tcpip-library-reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="if_nametoindex"
  26 HREF="net-common-tcpip-manpages-if-nametoindex.html"><LINK
  27 REL="NEXT"
  28 TITLE="inet6_option_space"
  29 HREF="net-common-tcpip-manpages-inet6-option-space.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-common-tcpip-manpages-if-nametoindex.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 38. TCP/IP Library Reference</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-common-tcpip-manpages-inet6-option-space.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-COMMON-TCPIP-MANPAGES-INET">inet</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >INET(3)                 System Library Functions Manual                INET(3)
  95
  96 NAME
  97      inet_addr, inet_aton, inet_lnaof, inet_makeaddr, inet_netof,
  98      inet_network, inet_ntoa, inet_ntop, inet_pton - Internet address manipu-
  99      lation routines
 100
 101 SYNOPSIS
 102      #include &lt;sys/socket.h&#62;
 103      #include &lt;netinet/in.h&#62;
 104      #include &lt;arpa/inet.h&#62;
 105
 106      in_addr_t
 107      inet_addr(const char *cp);
 108
 109      int
 110      inet_aton(const char *cp, struct in_addr *addr);
 111
 112      in_addr_t
 113      inet_lnaof(struct in_addr in);
 114
 115      struct in_addr
 116      inet_makeaddr(unsigned long net, unsigned long lna);
 117
 118      in_addr_t
 119      inet_netof(struct in_addr in);
 120
 121      in_addr_t
 122      inet_network(const char *cp);
 123
 124      char *
 125      inet_ntoa(struct in_addr in);
 126
 127      const char *
 128      inet_ntop(int af, const void *src, char *dst, size_t size);
 129
 130      int
 131      inet_pton(int af, const char *src, void *dst);
 132
 133 DESCRIPTION
 134      The routines inet_aton(), inet_addr() and inet_network() interpret char-
 135      acter strings representing numbers expressed in the Internet standard `.'
 136      notation.  The inet_pton() function converts a presentation format
 137      address (that is, printable form as held in a character string) to net-
 138      work format (usually a struct in_addr or some other internal binary rep-
 139      resentation, in network byte order).  It returns 1 if the address was
 140      valid for the specified address family, or 0 if the address wasn't
 141      parseable in the specified address family, or -1 if some system error
 142      occurred (in which case errno will have been set).  This function is
 143      presently valid for AF_INET and AF_INET6.  The inet_aton() routine inter-
 144      prets the specified character string as an Internet address, placing the
 145      address into the structure provided.  It returns 1 if the string was suc-
 146      cessfully interpreted, or 0 if the string was invalid.  The inet_addr()
 147      and inet_network() functions return numbers suitable for use as Internet
 148      addresses and Internet network numbers, respectively.
 149
 150      The function inet_ntop() converts an address from network format (usually
 151      a struct in_addr or some other binary form, in network byte order) to
 152      presentation format (suitable for external display purposes).  It returns
 153      NULL if a system error occurs (in which case, errno will have been set),
 154      or it returns a pointer to the destination string.  The routine
 155      inet_ntoa() takes an Internet address and returns an ASCII string repre-
 156      senting the address in `.' notation.  The routine inet_makeaddr() takes
 157      an Internet network number and a local network address and constructs an
 158      Internet address from it.  The routines inet_netof() and inet_lnaof()
 159      break apart Internet host addresses, returning the network number and
 160      local network address part, respectively.
 161
 162      All Internet addresses are returned in network order (bytes ordered from
 163      left to right).  All network numbers and local address parts are returned
 164      as machine format integer values.
 165
 166 INTERNET ADDRESSES (IP VERSION 4)
 167      Values specified using the `.' notation take one of the following forms:
 168
 169            a.b.c.d
 170            a.b.c
 171            a.b
 172            a
 173
 174      When four parts are specified, each is interpreted as a byte of data and
 175      assigned, from left to right, to the four bytes of an Internet address.
 176      Note that when an Internet address is viewed as a 32-bit integer quantity
 177      on a system that uses little-endian byte order (such as the Intel 386,
 178      486 and Pentium processors) the bytes referred to above appear as
 179      ``d.c.b.a''.  That is, little-endian bytes are ordered from right to
 180      left.
 181
 182      When a three part address is specified, the last part is interpreted as a
 183      16-bit quantity and placed in the rightmost two bytes of the network
 184      address.  This makes the three part address format convenient for speci-
 185      fying Class B network addresses as ``128.net.host''.
 186
 187      When a two part address is supplied, the last part is interpreted as a
 188      24-bit quantity and placed in the rightmost three bytes of the network
 189      address.  This makes the two part address format convenient for specify-
 190      ing Class A network addresses as ``net.host''.
 191
 192      When only one part is given, the value is stored directly in the network
 193      address without any byte rearrangement.
 194
 195      All numbers supplied as ``parts'' in a `.' notation may be decimal,
 196      octal, or hexadecimal, as specified in the C language (i.e., a leading 0x
 197      or 0X implies hexadecimal; otherwise, a leading 0 implies octal; other-
 198      wise, the number is interpreted as decimal).
 199
 200 INTERNET ADDRESSES (IP VERSION 6)
 201      In order to support scoped IPv6 addresses, getaddrinfo(3) and
 202      getnameinfo(3) are recommended rather than the functions presented here.
 203
 204      The presentation format of an IPv6 address is given in [RFC1884 2.2]:
 205
 206      There are three conventional forms for representing IPv6 addresses as
 207      text strings:
 208
 209      1.   The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the hex-
 210           adecimal values of the eight 16-bit pieces of the address.  Exam-
 211           ples:
 212
 213                 FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
 214                 1080:0:0:0:8:800:200C:417A
 215
 216           Note that it is not necessary to write the leading zeros in an indi-
 217           vidual field, but there must be at least one numeral in every field
 218           (except for the case described in 2.).
 219
 220      2.   Due to the method of allocating certain styles of IPv6 addresses, it
 221           will be common for addresses to contain long strings of zero bits.
 222           In order to make writing addresses
 223
 224           containing zero bits easier a special syntax is available to com-
 225           press the zeros.  The use of ``::'' indicates multiple groups of 16
 226           bits of zeros.  The ``::'' can only appear once in an address.  The
 227           ``::'' can also be used to compress the leading and/or trailing
 228           zeros in an address.
 229
 230           For example the following addresses:
 231
 232                 1080:0:0:0:8:800:200C:417A  a unicast address
 233                 FF01:0:0:0:0:0:0:43         a multicast address
 234                 0:0:0:0:0:0:0:1             the loopback address
 235                 0:0:0:0:0:0:0:0             the unspecified addresses
 236
 237           may be represented as:
 238
 239                 1080::8:800:200C:417A       a unicast address
 240                 FF01::43                    a multicast address
 241                 ::1                         the loopback address
 242                 ::                          the unspecified addresses
 243
 244      3.   An alternative form that is sometimes more convenient when dealing
 245           with a mixed environment of IPv4 and IPv6 nodes is
 246           x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values of
 247           the six high-order 16-bit pieces of the address, and the 'd's are
 248           the decimal values of the four low-order 8-bit pieces of the address
 249           (standard IPv4 representation).  Examples:
 250
 251                 0:0:0:0:0:0:13.1.68.3
 252                 0:0:0:0:0:FFFF:129.144.52.38
 253
 254           or in compressed form:
 255
 256                 ::13.1.68.3
 257                 ::FFFF:129.144.52.38
 258
 259 DIAGNOSTICS
 260      The constant INADDR_NONE is returned by inet_addr() and inet_network()
 261      for malformed requests.
 262
 263 SEE ALSO
 264      byteorder(3), gethostbyname(3), getnetent(3), inet_net(3), hosts(5),
 265      networks(5)
 266
 267 STANDARDS
 268      The inet_ntop and inet_pton functions conforms to the IETF IPv6 BSD API
 269      and address formatting specifications.  Note that inet_pton does not
 270      accept 1-, 2-, or 3-part dotted addresses; all four parts must be speci-
 271      fied.  This is a narrower input set than that accepted by inet_aton.
 272
 273 HISTORY
 274      The inet_addr, inet_network, inet_makeaddr, inet_lnaof and inet_netof
 275      functions appeared in 4.2BSD.  The inet_aton and inet_ntoa functions
 276      appeared in 4.3BSD.  The inet_pton and inet_ntop functions appeared in
 277      BIND 4.9.4.
 278
 279 BUGS
 280      The value INADDR_NONE (0xffffffff) is a valid broadcast address, but
 281      inet_addr() cannot return that value without indicating failure.  Also,
 282      inet_addr() should have been designed to return a struct in_addr.  The
 283      newer inet_aton() function does not share these problems, and almost all
 284      existing code should be modified to use inet_aton() instead.
 285
 286      The problem of host byte ordering versus network byte ordering is confus-
 287      ing.
 288
 289      The string returned by inet_ntoa() resides in a static memory area.
 290
 291 BSD                              June 18, 1997                             BSD
 292     </PRE
 293 ></TD
 294 ></TR
 295 ></TABLE
 296 ></DIV
 297 ><DIV
 298 CLASS="NAVFOOTER"
 299 ><HR
 300 ALIGN="LEFT"
 301 WIDTH="100%"><TABLE
 302 SUMMARY="Footer navigation table"
 303 WIDTH="100%"
 304 BORDER="0"
 305 CELLPADDING="0"
 306 CELLSPACING="0"
 307 ><TR
 308 ><TD
 309 WIDTH="33%"
 310 ALIGN="left"
 311 VALIGN="top"
 312 ><A
 313 HREF="net-common-tcpip-manpages-if-nametoindex.html"
 314 ACCESSKEY="P"
 315 >Prev</A
 316 ></TD
 317 ><TD
 318 WIDTH="34%"
 319 ALIGN="center"
 320 VALIGN="top"
 321 ><A
 322 HREF="ecos-ref.html"
 323 ACCESSKEY="H"
 324 >Home</A
 325 ></TD
 326 ><TD
 327 WIDTH="33%"
 328 ALIGN="right"
 329 VALIGN="top"
 330 ><A
 331 HREF="net-common-tcpip-manpages-inet6-option-space.html"
 332 ACCESSKEY="N"
 333 >Next</A
 334 ></TD
 335 ></TR
 336 ><TR
 337 ><TD
 338 WIDTH="33%"
 339 ALIGN="left"
 340 VALIGN="top"
 341 >if_nametoindex</TD
 342 ><TD
 343 WIDTH="34%"
 344 ALIGN="center"
 345 VALIGN="top"
 346 ><A
 347 HREF="tcpip-library-reference.html"
 348 ACCESSKEY="U"
 349 >Up</A
 350 ></TD
 351 ><TD
 352 WIDTH="33%"
 353 ALIGN="right"
 354 VALIGN="top"
 355 >inet6_option_space</TD
 356 ></TR
 357 ></TABLE
 358 ></DIV
 359 ></BODY
 360 ></HTML
 361 >