fbbd9655e5
Renumber cluase 4 to 3, per what everybody else did when BSD granted them permission to remove clause 3. My insistance on keeping the same numbering for legal reasons is too pedantic, so give up on that point. Submitted by: Jan Schaumann <jschauma@stevens.edu> Pull Request: https://github.com/freebsd/freebsd/pull/96
306 lines
7.8 KiB
Groff
306 lines
7.8 KiB
Groff
.\" Copyright (c) 1983, 1990, 1991, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" From: @(#)inet.3 8.1 (Berkeley) 6/4/93
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd June 14, 2007
|
|
.Dt INET 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm inet_aton ,
|
|
.Nm inet_addr ,
|
|
.Nm inet_network ,
|
|
.Nm inet_ntoa ,
|
|
.Nm inet_ntoa_r ,
|
|
.Nm inet_ntop ,
|
|
.Nm inet_pton ,
|
|
.Nm inet_makeaddr ,
|
|
.Nm inet_lnaof ,
|
|
.Nm inet_netof
|
|
.Nd Internet address manipulation routines
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.In sys/types.h
|
|
.In sys/socket.h
|
|
.In netinet/in.h
|
|
.In arpa/inet.h
|
|
.Ft int
|
|
.Fn inet_aton "const char *cp" "struct in_addr *pin"
|
|
.Ft in_addr_t
|
|
.Fn inet_addr "const char *cp"
|
|
.Ft in_addr_t
|
|
.Fn inet_network "const char *cp"
|
|
.Ft char *
|
|
.Fn inet_ntoa "struct in_addr in"
|
|
.Ft char *
|
|
.Fo inet_ntoa_r
|
|
.Fa "struct in_addr in"
|
|
.Fa "char *buf"
|
|
.Fa "socklen_t size"
|
|
.Fc
|
|
.Ft const char *
|
|
.Fo inet_ntop
|
|
.Fa "int af"
|
|
.Fa "const void * restrict src"
|
|
.Fa "char * restrict dst"
|
|
.Fa "socklen_t size"
|
|
.Fc
|
|
.Ft int
|
|
.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst"
|
|
.Ft struct in_addr
|
|
.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna"
|
|
.Ft in_addr_t
|
|
.Fn inet_lnaof "struct in_addr in"
|
|
.Ft in_addr_t
|
|
.Fn inet_netof "struct in_addr in"
|
|
.Sh DESCRIPTION
|
|
The routines
|
|
.Fn inet_aton ,
|
|
.Fn inet_addr
|
|
and
|
|
.Fn inet_network
|
|
interpret character strings representing
|
|
numbers expressed in the Internet standard
|
|
.Ql .\&
|
|
notation.
|
|
.Pp
|
|
The
|
|
.Fn inet_pton
|
|
function converts a presentation format address (that is, printable form
|
|
as held in a character string) to network format (usually a
|
|
.Ft struct in_addr
|
|
or some other internal binary representation, in network byte order).
|
|
It returns 1 if the address was valid for the specified address family, or
|
|
0 if the address was not parseable in the specified address family, or -1
|
|
if some system error occurred (in which case
|
|
.Va errno
|
|
will have been set).
|
|
This function is presently valid for
|
|
.Dv AF_INET
|
|
and
|
|
.Dv AF_INET6 .
|
|
.Pp
|
|
The
|
|
.Fn inet_aton
|
|
routine interprets the specified character string as an Internet address,
|
|
placing the address into the structure provided.
|
|
It returns 1 if the string was successfully interpreted,
|
|
or 0 if the string is invalid.
|
|
The
|
|
.Fn inet_addr
|
|
and
|
|
.Fn inet_network
|
|
functions return numbers suitable for use
|
|
as Internet addresses and Internet network
|
|
numbers, respectively.
|
|
.Pp
|
|
The function
|
|
.Fn inet_ntop
|
|
converts an address
|
|
.Fa *src
|
|
from network format
|
|
(usually a
|
|
.Ft struct in_addr
|
|
or some other binary form, in network byte order) to presentation format
|
|
(suitable for external display purposes).
|
|
The
|
|
.Fa size
|
|
argument specifies the size, in bytes, of the buffer
|
|
.Fa *dst .
|
|
.Dv INET_ADDRSTRLEN
|
|
and
|
|
.Dv INET6_ADDRSTRLEN
|
|
define the maximum size required to convert an address of the respective
|
|
type.
|
|
It returns NULL if a system error occurs (in which case,
|
|
.Va errno
|
|
will have been set), or it returns a pointer to the destination string.
|
|
This function is presently valid for
|
|
.Dv AF_INET
|
|
and
|
|
.Dv AF_INET6 .
|
|
.Pp
|
|
The routine
|
|
.Fn inet_ntoa
|
|
takes an Internet address and returns an
|
|
.Tn ASCII
|
|
string representing the address in
|
|
.Ql .\&
|
|
notation.
|
|
The routine
|
|
.Fn inet_ntoa_r
|
|
is the reentrant version of
|
|
.Fn inet_ntoa .
|
|
The routine
|
|
.Fn inet_makeaddr
|
|
takes an Internet network number and a local
|
|
network address and constructs an Internet address
|
|
from it.
|
|
The routines
|
|
.Fn inet_netof
|
|
and
|
|
.Fn inet_lnaof
|
|
break apart Internet host addresses, returning
|
|
the network number and local network address part,
|
|
respectively.
|
|
.Pp
|
|
All Internet addresses are returned in network
|
|
order (bytes ordered from left to right).
|
|
All network numbers and local address parts are
|
|
returned as machine byte order integer values.
|
|
.Sh INTERNET ADDRESSES
|
|
Values specified using the
|
|
.Ql .\&
|
|
notation take one
|
|
of the following forms:
|
|
.Bd -literal -offset indent
|
|
a.b.c.d
|
|
a.b.c
|
|
a.b
|
|
a
|
|
.Ed
|
|
.Pp
|
|
When four parts are specified, each is interpreted
|
|
as a byte of data and assigned, from left to right,
|
|
to the four bytes of an Internet address.
|
|
Note
|
|
that when an Internet address is viewed as a 32-bit
|
|
integer quantity on the
|
|
.Tn VAX
|
|
the bytes referred to
|
|
above appear as
|
|
.Dq Li d.c.b.a .
|
|
That is,
|
|
.Tn VAX
|
|
bytes are
|
|
ordered from right to left.
|
|
.Pp
|
|
When a three part address is specified, the last
|
|
part is interpreted as a 16-bit quantity and placed
|
|
in the right-most two bytes of the network address.
|
|
This makes the three part address format convenient
|
|
for specifying Class B network addresses as
|
|
.Dq Li 128.net.host .
|
|
.Pp
|
|
When a two part address is supplied, the last part
|
|
is interpreted as a 24-bit quantity and placed in
|
|
the right most three bytes of the network address.
|
|
This makes the two part address format convenient
|
|
for specifying Class A network addresses as
|
|
.Dq Li net.host .
|
|
.Pp
|
|
When only one part is given, the value is stored
|
|
directly in the network address without any byte
|
|
rearrangement.
|
|
.Pp
|
|
All numbers supplied as
|
|
.Dq parts
|
|
in a
|
|
.Ql .\&
|
|
notation
|
|
may be decimal, octal, or hexadecimal, as specified
|
|
in the C language (i.e., a leading 0x or 0X implies
|
|
hexadecimal; otherwise, a leading 0 implies octal;
|
|
otherwise, the number is interpreted as decimal).
|
|
.Sh DIAGNOSTICS
|
|
The constant
|
|
.Dv INADDR_NONE
|
|
is returned by
|
|
.Fn inet_addr
|
|
and
|
|
.Fn inet_network
|
|
for malformed requests.
|
|
.Sh ERRORS
|
|
The
|
|
.Fn inet_ntop
|
|
call fails if:
|
|
.Bl -tag -width Er
|
|
.It Bq Er ENOSPC
|
|
.Fa size
|
|
was not large enough to store the presentation form of the address.
|
|
.It Bq Er EAFNOSUPPORT
|
|
.Fa *src
|
|
was not an
|
|
.Dv AF_INET
|
|
or
|
|
.Dv AF_INET6
|
|
family address.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr byteorder 3 ,
|
|
.Xr getaddrinfo 3 ,
|
|
.Xr gethostbyname 3 ,
|
|
.Xr getnameinfo 3 ,
|
|
.Xr getnetent 3 ,
|
|
.Xr inet_net 3 ,
|
|
.Xr hosts 5 ,
|
|
.Xr networks 5
|
|
.Rs
|
|
.%R RFC
|
|
.%N 2373
|
|
.%D July 1998
|
|
.%T "IP Version 6 Addressing Architecture"
|
|
.Re
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn inet_ntop
|
|
and
|
|
.Fn inet_pton
|
|
functions conform to
|
|
.St -xns5.2 .
|
|
Note that
|
|
.Fn inet_pton
|
|
does not accept 1-, 2-, or 3-part dotted addresses; all four parts
|
|
must be specified and are interpreted only as decimal values.
|
|
This is a narrower input set than that accepted by
|
|
.Fn inet_aton .
|
|
.Sh HISTORY
|
|
These
|
|
functions appeared in
|
|
.Bx 4.2 .
|
|
.Sh BUGS
|
|
The value
|
|
.Dv INADDR_NONE
|
|
(0xffffffff) is a valid broadcast address, but
|
|
.Fn inet_addr
|
|
cannot return that value without indicating failure.
|
|
The newer
|
|
.Fn inet_aton
|
|
function does not share this problem.
|
|
The problem of host byte ordering versus network byte ordering is
|
|
confusing.
|
|
The string returned by
|
|
.Fn inet_ntoa
|
|
resides in a static memory area.
|
|
.Pp
|
|
The
|
|
.Fn inet_addr
|
|
function should return a
|
|
.Fa struct in_addr .
|