sync

[thirdparty/man-pages.git] / man3 / inet.3

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
.\"
.\" 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.
.\"
.TH INET 3  2001-07-25 "BSD" "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
.SH DESCRIPTION
\fBinet_aton\fP() 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. \fBinet_aton\fP() returns
non-zero if the address is valid, zero if not.
.PP
The \fBinet_addr\fP() function converts the Internet host address
\fIcp\fP from numbers-and-dots notation into binary data in network
byte order.
If the input is invalid, INADDR_NONE (usually \-1) is returned.
This is an \fIobsolete\fP interface to \fBinet_aton\fP(), described
immediately above; it is obsolete because \-1 is a valid address
(255.255.255.255), and \fBinet_aton\fP() provides a cleaner way
to indicate error return.
.PP
The \fBinet_network\fP() 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.
If the input is invalid, \-1 is returned.
.PP
The \fBinet_ntoa\fP() function converts the Internet host address
\fIin\fP given in network byte order to a string in standard
numbers-and-dots notation.
The string is returned in a statically
allocated buffer, which subsequent calls will overwrite.
.PP
The \fBinet_makeaddr\fP() 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 \fBinet_lnaof\fP() function returns the local host address part
of the Internet address \fIin\fP.
The local host address is returned
in local host byte order.
.PP
The \fBinet_netof\fP() function returns the network number part of
the Internet Address \fIin\fP.
The network number is returned in
local host byte order.
.PP
The structure \fIin_addr\fP as used in \fBinet_ntoa\fP(),
\fBinet_makeaddr\fP(), \fBinet_lnoaf\fP() and \fBinet_netof\fP()
is defined in \fInetinet/in.h\fP as:
.sp
.RS
.nf
struct in_addr {
    unsigned long int s_addr;
}
.fi
.RE
.PP
Note that on the i80x86 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 NOTE
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.
.SH "GLIBC NOTES"
In order to expose the declaration of
.BR inet_aton (),
one of the feature test macros _BSD_SOURCE, _SVID_SOURCE, or
_GNU_SOURCE must be defined.
.SH "CONFORMING TO"
4.3BSD.
.BR inet_addr (),
.BR inet_aton (),
and
.BR inet_ntoa ()
are specified in POSIX.1-2001.
.SH "SEE ALSO"
.BR gethostbyname (3),
.BR getnetent (3),
.BR inet_ntop (3),
.BR inet_pton (3),
.BR hosts (5),
.BR networks (5)