mirror of https://github.com/mkerrisk/man-pages
305 lines
8.5 KiB
Groff
305 lines
8.5 KiB
Groff
.\" 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
|
|
.\" 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.
|
|
.\"
|
|
.\" 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 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
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/socket.h>
|
|
.B #include <netinet/in.h>
|
|
.B #include <arpa/inet.h>
|
|
.sp
|
|
.BI "int inet_aton(const char *" cp ", struct in_addr *" inp );
|
|
.sp
|
|
.BI "in_addr_t inet_addr(const char *" cp );
|
|
.sp
|
|
.BI "in_addr_t inet_network(const char *" cp );
|
|
.sp
|
|
.BI "char *inet_ntoa(struct in_addr " in );
|
|
.sp
|
|
.BI "struct in_addr inet_makeaddr(int " net ", int " host );
|
|
.sp
|
|
.BI "in_addr_t inet_lnaof(struct in_addr " in );
|
|
.sp
|
|
.BI "in_addr_t inet_netof(struct in_addr " in );
|
|
.fi
|
|
.sp
|
|
.in -4n
|
|
Feature Test Macro Requirements for glibc (see
|
|
.BR feature_test_macros (7)):
|
|
.in
|
|
.sp
|
|
.BR inet_aton (),
|
|
.BR inet_ntoa ():
|
|
_BSD_SOURCE || _SVID_SOURCE
|
|
.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 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 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:
|
|
.sp
|
|
.in +4n
|
|
.nf
|
|
typedef uint32_t in_addr_t;
|
|
|
|
struct in_addr {
|
|
in_addr_t s_addr;
|
|
};
|
|
.fi
|
|
.in
|
|
.SH "CONFORMING TO"
|
|
4.3BSD.
|
|
.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
|
|
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),
|
|
.BR hosts (5),
|
|
.BR networks (5)
|