mirror of https://github.com/mkerrisk/man-pages
inet_aton() is *not* in POSIX.1.
Rewrite discussion of why inet_addr() is disfavored. SEE ALSO: Add getaddrinfo(3). as per http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=482979. Describe the various address forms supported by inet_aton(). Rewrite description of inet_network(). Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr(). Add discussion of Classful Addressing, noting that it is obsolete. Added an EXAMPLE program. Relocate discussion of i386 byte order to NOTES. Note that inet_aton() returns an address in network byte order. SEE ALSO: Add byteorder(3) and getnameinfo(3).
This commit is contained in:
Michael Kerrisk
parent
444aa1ce8c
commit
054f5228c6
216
man3/inet.3
216
man3/inet.3
|
|
@ -1,6 +1,7 @@
|
|||
.\" Hey Emacs! This file is -*- nroff -*- source.
|
||||
.\"
|
||||
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
||||
.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk <mtk.manpages@gmail.com>
|
||||
.\"
|
||||
.\" Permission is granted to make and distribute verbatim copies of this
|
||||
.\" manual provided the copyright notice and this permission notice are
|
||||
|
|
@ -31,8 +32,13 @@
|
|||
.\" Modified Sun Sep 3 20:29:36 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
|
||||
.\" Changed network into host byte order (for inet_network),
|
||||
.\" Andreas Jaeger <aj@arthur.rhein-neckar.de>, 980130.
|
||||
.\" 2008-06-19, mtk
|
||||
.\" Describe the various address forms supported by inet_aton().
|
||||
.\" Clarify discussion of inet_lnaof(), inet_netof(), and inet_makeaddr().
|
||||
.\" Add discussion of Classful Addressing, noting that it is obsolete.
|
||||
.\" Added an EXAMPLE program.
|
||||
.\"
|
||||
.TH INET 3 2007-07-26 "GNU" "Linux Programmer's Manual"
|
||||
.TH INET 3 2008-06-19 "GNU" "Linux Programmer's Manual"
|
||||
.SH NAME
|
||||
inet_aton, inet_addr, inet_network, inet_ntoa, inet_makeaddr, inet_lnaof,
|
||||
inet_netof \- Internet address manipulation routines
|
||||
|
|
@ -68,64 +74,118 @@ _BSD_SOURCE || _SVID_SOURCE
|
|||
.SH DESCRIPTION
|
||||
.BR inet_aton ()
|
||||
converts the Internet host address \fIcp\fP from the
|
||||
standard numbers-and-dots notation into binary data and stores it in
|
||||
the structure that \fIinp\fP points to.
|
||||
IPv4 numbers-and-dots notation into binary form (in network byte order)
|
||||
and stores it in the structure that \fIinp\fP points to.
|
||||
.BR inet_aton ()
|
||||
returns
|
||||
non-zero if the address is valid, zero if not.
|
||||
returns non-zero if the address is valid, zero if not.
|
||||
The address supplied in
|
||||
.I cp
|
||||
can have one of the following forms:
|
||||
.TP 10
|
||||
.I a.b.c.d
|
||||
Each of the for numeric parts specifies a byte of the address;
|
||||
the bytes are assigned in left-to-right order to produce the binary address.
|
||||
.TP
|
||||
.I a.b.c
|
||||
Parts
|
||||
.I a
|
||||
and
|
||||
.I b
|
||||
specify the first two bytes of the binary address.
|
||||
Part
|
||||
.I c
|
||||
is interpreted as a 16-bit value that defines the rightmost two bytes
|
||||
of the binary address.
|
||||
This notation is suitable for specifying (outmoded) Class B
|
||||
network addresses.
|
||||
.TP
|
||||
.I a.b
|
||||
Part
|
||||
.I a
|
||||
specifies the first byte of the binary address.
|
||||
Part
|
||||
.I b
|
||||
is interpreted as a 24-bit value that defines the rightmost three bytes
|
||||
of the binary address.
|
||||
This notation is suitable for specifying (outmoded) Class C
|
||||
network addresses.
|
||||
.TP
|
||||
.I a
|
||||
The value
|
||||
.I a
|
||||
is interpreted as a 32-bit value that is stored directly
|
||||
into the binary address without any byte rearrangement.
|
||||
.PP
|
||||
In all of the above forms,
|
||||
components of the dotted address can be specified in decimal,
|
||||
octal (with a leading
|
||||
.IR 0 ),
|
||||
or hexadecimal, with a leading
|
||||
.IR 0X ).
|
||||
Addresses in any of these forms are collectively termed
|
||||
.IR "IPV4 numbers-and-dots notation" .
|
||||
The form that uses exactly four decimal numbers is referred to as
|
||||
.IR "IPv4 dotted-decimal notation"
|
||||
(or sometimes:
|
||||
.IR "IPv4 dotted-quad notation" ).
|
||||
.PP
|
||||
The
|
||||
.BR inet_addr ()
|
||||
function converts the Internet host address
|
||||
\fIcp\fP from numbers-and-dots notation into binary data in network
|
||||
\fIcp\fP from IPv4 numbers-and-dots notation into binary data in network
|
||||
byte order.
|
||||
If the input is invalid,
|
||||
.B INADDR_NONE
|
||||
(usually \-1) is returned.
|
||||
This is an \fIobsolete\fP interface to
|
||||
Use of this function is problematic because \-1 is a valid address
|
||||
(255.255.255.255).
|
||||
Avoid its use in favor of
|
||||
.BR inet_aton (),
|
||||
described
|
||||
immediately above; it is obsolete because \-1 is a valid address
|
||||
(255.255.255.255), and
|
||||
.BR inet_aton ()
|
||||
provides a cleaner way
|
||||
to indicate error return.
|
||||
.BR inet_pton (3),
|
||||
or
|
||||
.BR getaddrinfo (3)
|
||||
which provide a cleaner way to indicate error return.
|
||||
.PP
|
||||
The
|
||||
.BR inet_network ()
|
||||
function extracts
|
||||
a number in host byte order suitable for use as an Internet address
|
||||
from \fIcp\fP, which is a string in numbers-and-dots notation.
|
||||
function converts
|
||||
.IR cp ,
|
||||
a string in IPv4 numbers-and-dots notation,
|
||||
into a number in host byte order suitable for use as an
|
||||
Internet network address.
|
||||
On success, the converted address is returned.
|
||||
If the input is invalid, \-1 is returned.
|
||||
.PP
|
||||
The
|
||||
.BR inet_ntoa ()
|
||||
function converts the Internet host address
|
||||
\fIin\fP given in network byte order to a string in standard
|
||||
numbers-and-dots notation.
|
||||
\fIin\fP, given in network byte order, to a string in IPv4
|
||||
dotted-decimal notation.
|
||||
The string is returned in a statically
|
||||
allocated buffer, which subsequent calls will overwrite.
|
||||
.PP
|
||||
The
|
||||
.BR inet_makeaddr ()
|
||||
function makes an Internet host address
|
||||
in network byte order by combining the network number \fInet\fP
|
||||
with the local address \fIhost\fP in network \fInet\fP, both in
|
||||
local host byte order.
|
||||
.PP
|
||||
The
|
||||
.BR inet_lnaof ()
|
||||
function returns the local host address part
|
||||
function returns the local network address part
|
||||
of the Internet address \fIin\fP.
|
||||
The local host address is returned
|
||||
in local host byte order.
|
||||
The returned value is in host byte order.
|
||||
.PP
|
||||
The
|
||||
.BR inet_netof ()
|
||||
function returns the network number part of
|
||||
the Internet Address \fIin\fP.
|
||||
The network number is returned in
|
||||
local host byte order.
|
||||
the Internet address \fIin\fP.
|
||||
The returned value is in host byte order.
|
||||
.PP
|
||||
The
|
||||
.BR inet_makeaddr ()
|
||||
function is the converse of
|
||||
.BR inet_netof()
|
||||
and
|
||||
.BR inet_lnaof ().
|
||||
It returns an Internet host address in network byte order,
|
||||
created by combining the network number \fInet\fP
|
||||
with the local address \fIhost\fP, both in
|
||||
host byte order.
|
||||
.PP
|
||||
The structure \fIin_addr\fP as used in
|
||||
.BR inet_ntoa (),
|
||||
|
|
@ -146,25 +206,97 @@ struct in_addr {
|
|||
};
|
||||
.fi
|
||||
.in
|
||||
.PP
|
||||
Note that on the i386 the host byte order is Least Significant Byte
|
||||
first (little endian), whereas the network byte order, as used on the
|
||||
Internet, is Most Significant Byte first (big endian).
|
||||
.SH "CONFORMING TO"
|
||||
4.3BSD.
|
||||
.BR inet_addr (),
|
||||
.BR inet_aton (),
|
||||
.BR inet_addr ()
|
||||
and
|
||||
.BR inet_ntoa ()
|
||||
are specified in POSIX.1-2001.
|
||||
.BR inet_aton ()
|
||||
is not specified in POSIX.1.-2001, but is available on most systems.
|
||||
.SH NOTES
|
||||
When you using numbers-and-dots notation for addresses,
|
||||
be aware that each number will be interpreted as octal
|
||||
if preceded by a 0 and as hexadecimal if preceded by 0x.
|
||||
For example, \fBinet_aton("226.000.000.037", &t)\fP will
|
||||
interpret the address as \fI226.0.0.31\fP and not \fI226.0.0.37\fP.
|
||||
On the i386 the host byte order is Least Significant Byte
|
||||
first (little endian), whereas the network byte order, as used on the
|
||||
Internet, is Most Significant Byte first (big endian).
|
||||
|
||||
.BR inet_lnaof (),
|
||||
.BR inet_netof (),
|
||||
and
|
||||
.BR inet_makeaddr ()
|
||||
are legacy functions that assume they are dealing with
|
||||
.IR "classful network addresses" .
|
||||
Classful networking divides IPv4 network addresses into host and network
|
||||
components at byte boundaries, as follows:
|
||||
.TP 10
|
||||
Class A
|
||||
This address type is indicated by the value 0 in the
|
||||
most significant bit of the (network byte ordered) address.
|
||||
The network address is contained in the most significant byte,
|
||||
and the host address occupies the remaining three bytes.
|
||||
.TP
|
||||
Class B
|
||||
This address type is indicated by the binary value 10 in the
|
||||
most significant two bits of the address.
|
||||
The network address is contained in the two most significant bytes,
|
||||
and the host address occupies the remaining two bytes.
|
||||
.TP
|
||||
Class C
|
||||
This address type is indicated by the binary value 110 in the
|
||||
most significant three bits of the address.
|
||||
The network address is contained in the three most significant bytes,
|
||||
and the host address occupies the remaining byte.
|
||||
.PP
|
||||
Classful network addresses are now obolete,
|
||||
having been superseded by Classless Inter-Domain Routing (CIDR),
|
||||
which divides addresses into network and host components at
|
||||
arbitrary bit (rather than byte) boundaries.
|
||||
.SH EXAMPLE
|
||||
An example of the use of
|
||||
.BR inet_aton ()
|
||||
and
|
||||
.BR inet_ntoa ()
|
||||
is shown below.
|
||||
Here are some example runs:
|
||||
.in +4n
|
||||
.nf
|
||||
|
||||
$ ./a.out 226.000.000.037 # Last byte is in octal
|
||||
226.0.0.31
|
||||
$ ./a.out 0x7f.1 # First byte is in hex
|
||||
127.0.0.1
|
||||
|
||||
.fi
|
||||
.in
|
||||
.nf
|
||||
#define _BSD_SOURCE
|
||||
#include <arpa/inet.h>
|
||||
#include <stdio.h>
|
||||
#include <stdlib.h>
|
||||
|
||||
int
|
||||
main(int argc, char *argv[])
|
||||
{
|
||||
struct in_addr addr;
|
||||
|
||||
if (argc != 2) {
|
||||
fprintf(stderr, "%s <dotted\-address>\\n", argv[0]);
|
||||
exit(EXIT_FAILURE);
|
||||
}
|
||||
|
||||
if (inet_aton(argv[1], &addr) == 0) {
|
||||
perror("inet_aton");
|
||||
exit(EXIT_FAILURE);
|
||||
}
|
||||
|
||||
printf("%s\\n", inet_ntoa(addr));
|
||||
exit(EXIT_SUCCESS);
|
||||
}
|
||||
.fi
|
||||
.SH "SEE ALSO"
|
||||
.BR byteorder (3),
|
||||
.BR getaddrinfo (3),
|
||||
.BR gethostbyname (3),
|
||||
.BR getnameinfo (3),
|
||||
.BR getnetent (3),
|
||||
.BR inet_ntop (3),
|
||||
.BR inet_pton (3),
|
||||
|
|
|
|||
Loading…
Reference in New Issue