mirror of https://github.com/mkerrisk/man-pages
343 lines
9.2 KiB
Groff
343 lines
9.2 KiB
Groff
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
|
|
.\" and Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
|
|
.\" <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" References consulted:
|
|
.\" Linux libc source code
|
|
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
|
|
.\" 386BSD man pages
|
|
.\" libc.info (from glibc distribution)
|
|
.\" Modified Sat Jul 24 19:12:00 1993 by Rik Faith <faith@cs.unc.edu>
|
|
.\" 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 2021-03-22 "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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/socket.h>
|
|
.B #include <netinet/in.h>
|
|
.B #include <arpa/inet.h>
|
|
.PP
|
|
.BI "int inet_aton(const char *" cp ", struct in_addr *" inp );
|
|
.PP
|
|
.BI "in_addr_t inet_addr(const char *" cp );
|
|
.BI "in_addr_t inet_network(const char *" cp );
|
|
.PP
|
|
.BI "char *inet_ntoa(struct in_addr " in );
|
|
.PP
|
|
.BI "struct in_addr inet_makeaddr(in_addr_t " net ", in_addr_t " host );
|
|
.PP
|
|
.BI "in_addr_t inet_lnaof(struct in_addr " in );
|
|
.BI "in_addr_t inet_netof(struct in_addr " in );
|
|
.fi
|
|
.PP
|
|
.RS -4
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.RE
|
|
.PP
|
|
.BR inet_aton (),
|
|
.BR inet_ntoa ():
|
|
.nf
|
|
Since glibc 2.19:
|
|
_DEFAULT_SOURCE
|
|
In glibc up to and including 2.19:
|
|
_BSD_SOURCE || _BSD_SOURCE
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.BR inet_aton ()
|
|
converts the Internet host address \fIcp\fP from the
|
|
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 nonzero 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 four 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 A
|
|
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
|
|
.BR inet_aton ()
|
|
returns 1 if the supplied string was successfully interpreted,
|
|
or 0 if the string is invalid
|
|
.RB ( errno
|
|
is
|
|
.I not
|
|
set on error).
|
|
.PP
|
|
The
|
|
.BR inet_addr ()
|
|
function converts the Internet host address
|
|
\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.
|
|
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 (),
|
|
.BR inet_pton (3),
|
|
or
|
|
.BR getaddrinfo (3),
|
|
which provide a cleaner way to indicate error return.
|
|
.PP
|
|
The
|
|
.BR inet_network ()
|
|
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 IPv4
|
|
dotted-decimal notation.
|
|
The string is returned in a statically
|
|
allocated buffer, which subsequent calls will overwrite.
|
|
.PP
|
|
The
|
|
.BR inet_lnaof ()
|
|
function returns the local network address part
|
|
of the Internet address \fIin\fP.
|
|
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 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 (),
|
|
.BR inet_makeaddr (),
|
|
.BR inet_lnaof (),
|
|
and
|
|
.BR inet_netof ()
|
|
is defined in
|
|
.I <netinet/in.h>
|
|
as:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
typedef uint32_t in_addr_t;
|
|
|
|
struct in_addr {
|
|
in_addr_t s_addr;
|
|
};
|
|
.EE
|
|
.in
|
|
.SH ATTRIBUTES
|
|
For an explanation of the terms used in this section, see
|
|
.BR attributes (7).
|
|
.ad l
|
|
.nh
|
|
.TS
|
|
allbox;
|
|
lbx lb lb
|
|
l l l.
|
|
Interface Attribute Value
|
|
T{
|
|
.BR inet_aton (),
|
|
.BR inet_addr (),
|
|
.BR inet_network (),
|
|
.BR inet_ntoa ()
|
|
T} Thread safety MT-Safe locale
|
|
T{
|
|
.BR inet_makeaddr (),
|
|
.BR inet_lnaof (),
|
|
.BR inet_netof ()
|
|
T} Thread safety MT-Safe
|
|
.TE
|
|
.hy
|
|
.ad
|
|
.sp 1
|
|
.SH CONFORMING TO
|
|
.BR inet_addr (),
|
|
.BR inet_ntoa ():
|
|
POSIX.1-2001, POSIX.1-2008, 4.3BSD.
|
|
.PP
|
|
.BR inet_aton ()
|
|
is not specified in POSIX.1, but is available on most systems.
|
|
.SH NOTES
|
|
On x86 architectures, 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).
|
|
.PP
|
|
.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 obsolete,
|
|
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 EXAMPLES
|
|
An example of the use of
|
|
.BR inet_aton ()
|
|
and
|
|
.BR inet_ntoa ()
|
|
is shown below.
|
|
Here are some example runs:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
.RB "$" " ./a.out 226.000.000.037" " # Last byte is in octal"
|
|
226.0.0.31
|
|
.RB "$" " ./a.out 0x7f.1 " " # First byte is in hex"
|
|
127.0.0.1
|
|
.EE
|
|
.in
|
|
.SS Program source
|
|
\&
|
|
.EX
|
|
#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>\en", argv[0]);
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
if (inet_aton(argv[1], &addr) == 0) {
|
|
fprintf(stderr, "Invalid address\en");
|
|
exit(EXIT_FAILURE);
|
|
}
|
|
|
|
printf("%s\en", inet_ntoa(addr));
|
|
exit(EXIT_SUCCESS);
|
|
}
|
|
.EE
|
|
.SH SEE ALSO
|
|
.BR byteorder (3),
|
|
.BR getaddrinfo (3),
|
|
.BR gethostbyname (3),
|
|
.BR getnameinfo (3),
|
|
.BR getnetent (3),
|
|
.BR inet_net_pton (3),
|
|
.BR inet_ntop (3),
|
|
.BR inet_pton (3),
|
|
.BR hosts (5),
|
|
.BR networks (5)
|