xref: /freebsd/lib/libc/net/inet.3 (revision 433671e34863146ef533f24e1ab8329d49a05ed0)
158f0484fSRodney W. Grimes.\" Copyright (c) 1983, 1990, 1991, 1993
258f0484fSRodney W. Grimes.\"	The Regents of the University of California.  All rights reserved.
358f0484fSRodney W. Grimes.\"
458f0484fSRodney W. Grimes.\" Redistribution and use in source and binary forms, with or without
558f0484fSRodney W. Grimes.\" modification, are permitted provided that the following conditions
658f0484fSRodney W. Grimes.\" are met:
758f0484fSRodney W. Grimes.\" 1. Redistributions of source code must retain the above copyright
858f0484fSRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer.
958f0484fSRodney W. Grimes.\" 2. Redistributions in binary form must reproduce the above copyright
1058f0484fSRodney W. Grimes.\"    notice, this list of conditions and the following disclaimer in the
1158f0484fSRodney W. Grimes.\"    documentation and/or other materials provided with the distribution.
1258f0484fSRodney W. Grimes.\" 3. All advertising materials mentioning features or use of this software
1358f0484fSRodney W. Grimes.\"    must display the following acknowledgement:
1458f0484fSRodney W. Grimes.\"	This product includes software developed by the University of
1558f0484fSRodney W. Grimes.\"	California, Berkeley and its contributors.
1658f0484fSRodney W. Grimes.\" 4. Neither the name of the University nor the names of its contributors
1758f0484fSRodney W. Grimes.\"    may be used to endorse or promote products derived from this software
1858f0484fSRodney W. Grimes.\"    without specific prior written permission.
1958f0484fSRodney W. Grimes.\"
2058f0484fSRodney W. Grimes.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
2158f0484fSRodney W. Grimes.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
2258f0484fSRodney W. Grimes.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
2358f0484fSRodney W. Grimes.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
2458f0484fSRodney W. Grimes.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
2558f0484fSRodney W. Grimes.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
2658f0484fSRodney W. Grimes.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
2758f0484fSRodney W. Grimes.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
2858f0484fSRodney W. Grimes.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
2958f0484fSRodney W. Grimes.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
3058f0484fSRodney W. Grimes.\" SUCH DAMAGE.
3158f0484fSRodney W. Grimes.\"
32538e8768SGarrett Wollman.\"     From: @(#)inet.3	8.1 (Berkeley) 6/4/93
33433671e3SBruce Evans.\"	$Id: inet.3,v 1.5 1997/02/22 15:00:15 peter Exp $
3458f0484fSRodney W. Grimes.\"
35538e8768SGarrett Wollman.Dd June 17, 1996
3658f0484fSRodney W. Grimes.Dt INET 3
3758f0484fSRodney W. Grimes.Os BSD 4.2
3858f0484fSRodney W. Grimes.Sh NAME
3958f0484fSRodney W. Grimes.Nm inet_aton ,
4058f0484fSRodney W. Grimes.Nm inet_addr ,
4158f0484fSRodney W. Grimes.Nm inet_network ,
4258f0484fSRodney W. Grimes.Nm inet_ntoa ,
4358f0484fSRodney W. Grimes.Nm inet_makeaddr ,
4458f0484fSRodney W. Grimes.Nm inet_lnaof ,
4558f0484fSRodney W. Grimes.Nm inet_netof
4658f0484fSRodney W. Grimes.Nd Internet address manipulation routines
4758f0484fSRodney W. Grimes.Sh SYNOPSIS
48433671e3SBruce Evans.Fd #include <sys/types.h>
4958f0484fSRodney W. Grimes.Fd #include <sys/socket.h>
5058f0484fSRodney W. Grimes.Fd #include <netinet/in.h>
5158f0484fSRodney W. Grimes.Fd #include <arpa/inet.h>
5258f0484fSRodney W. Grimes.Ft int
53433671e3SBruce Evans.Fn inet_aton "const char *cp" "struct in_addr *pin"
5458f0484fSRodney W. Grimes.Ft unsigned long
55433671e3SBruce Evans.Fn inet_addr "const char *cp"
5658f0484fSRodney W. Grimes.Ft unsigned long
57433671e3SBruce Evans.Fn inet_network "const char *cp"
5858f0484fSRodney W. Grimes.Ft char *
5958f0484fSRodney W. Grimes.Fn inet_ntoa "struct in_addr in"
6058f0484fSRodney W. Grimes.Ft struct in_addr
61433671e3SBruce Evans.Fn inet_makeaddr "unsigned long net" "unsigned long lna"
6258f0484fSRodney W. Grimes.Ft unsigned long
6358f0484fSRodney W. Grimes.Fn inet_lnaof "struct in_addr in"
6458f0484fSRodney W. Grimes.Ft unsigned long
6558f0484fSRodney W. Grimes.Fn inet_netof "struct in_addr in"
6658f0484fSRodney W. Grimes.Sh DESCRIPTION
6758f0484fSRodney W. GrimesThe routines
6858f0484fSRodney W. Grimes.Fn inet_aton ,
6958f0484fSRodney W. Grimes.Fn inet_addr
7058f0484fSRodney W. Grimesand
7158f0484fSRodney W. Grimes.Fn inet_network
7258f0484fSRodney W. Grimesinterpret character strings representing
7358f0484fSRodney W. Grimesnumbers expressed in the Internet standard
7458f0484fSRodney W. Grimes.Ql \&.
7558f0484fSRodney W. Grimesnotation.
7658f0484fSRodney W. GrimesThe
7758f0484fSRodney W. Grimes.Fn inet_aton
7858f0484fSRodney W. Grimesroutine interprets the specified character string as an Internet address,
7958f0484fSRodney W. Grimesplacing the address into the structure provided.
8058f0484fSRodney W. GrimesIt returns 1 if the string was successfully interpreted,
8158f0484fSRodney W. Grimesor 0 if the string is invalid.
8258f0484fSRodney W. GrimesThe
8358f0484fSRodney W. Grimes.Fn inet_addr
8458f0484fSRodney W. Grimesand
8558f0484fSRodney W. Grimes.Fn inet_network
8658f0484fSRodney W. Grimesfunctions return numbers suitable for use
8758f0484fSRodney W. Grimesas Internet addresses and Internet network
8858f0484fSRodney W. Grimesnumbers, respectively.
8958f0484fSRodney W. GrimesThe routine
9058f0484fSRodney W. Grimes.Fn inet_ntoa
9158f0484fSRodney W. Grimestakes an Internet address and returns an
9258f0484fSRodney W. Grimes.Tn ASCII
9358f0484fSRodney W. Grimesstring representing the address in
9458f0484fSRodney W. Grimes.Ql \&.
9558f0484fSRodney W. Grimesnotation.  The routine
9658f0484fSRodney W. Grimes.Fn inet_makeaddr
9758f0484fSRodney W. Grimestakes an Internet network number and a local
9858f0484fSRodney W. Grimesnetwork address and constructs an Internet address
9958f0484fSRodney W. Grimesfrom it.  The routines
10058f0484fSRodney W. Grimes.Fn inet_netof
10158f0484fSRodney W. Grimesand
10258f0484fSRodney W. Grimes.Fn inet_lnaof
10358f0484fSRodney W. Grimesbreak apart Internet host addresses, returning
10458f0484fSRodney W. Grimesthe network number and local network address part,
10558f0484fSRodney W. Grimesrespectively.
10658f0484fSRodney W. Grimes.Pp
10758f0484fSRodney W. GrimesAll Internet addresses are returned in network
10858f0484fSRodney W. Grimesorder (bytes ordered from left to right).
10958f0484fSRodney W. GrimesAll network numbers and local address parts are
11058f0484fSRodney W. Grimesreturned as machine format integer values.
11158f0484fSRodney W. Grimes.Sh INTERNET ADDRESSES
11258f0484fSRodney W. GrimesValues specified using the
11358f0484fSRodney W. Grimes.Ql \&.
11458f0484fSRodney W. Grimesnotation take one
11558f0484fSRodney W. Grimesof the following forms:
11658f0484fSRodney W. Grimes.Bd -literal -offset indent
11758f0484fSRodney W. Grimesa.b.c.d
11858f0484fSRodney W. Grimesa.b.c
11958f0484fSRodney W. Grimesa.b
12058f0484fSRodney W. Grimesa
12158f0484fSRodney W. Grimes.Ed
12258f0484fSRodney W. Grimes.Pp
12358f0484fSRodney W. GrimesWhen four parts are specified, each is interpreted
12458f0484fSRodney W. Grimesas a byte of data and assigned, from left to right,
12558f0484fSRodney W. Grimesto the four bytes of an Internet address.  Note
12658f0484fSRodney W. Grimesthat when an Internet address is viewed as a 32-bit
12758f0484fSRodney W. Grimesinteger quantity on the
12858f0484fSRodney W. Grimes.Tn VAX
12958f0484fSRodney W. Grimesthe bytes referred to
13058f0484fSRodney W. Grimesabove appear as
13158f0484fSRodney W. Grimes.Dq Li d.c.b.a .
13258f0484fSRodney W. GrimesThat is,
13358f0484fSRodney W. Grimes.Tn VAX
13458f0484fSRodney W. Grimesbytes are
13558f0484fSRodney W. Grimesordered from right to left.
13658f0484fSRodney W. Grimes.Pp
13758f0484fSRodney W. GrimesWhen a three part address is specified, the last
13858f0484fSRodney W. Grimespart is interpreted as a 16-bit quantity and placed
13958f0484fSRodney W. Grimesin the right-most two bytes of the network address.
14058f0484fSRodney W. GrimesThis makes the three part address format convenient
14158f0484fSRodney W. Grimesfor specifying Class B network addresses as
14258f0484fSRodney W. Grimes.Dq Li 128.net.host .
14358f0484fSRodney W. Grimes.Pp
14458f0484fSRodney W. GrimesWhen a two part address is supplied, the last part
14558f0484fSRodney W. Grimesis interpreted as a 24-bit quantity and placed in
14658f0484fSRodney W. Grimesthe right most three bytes of the network address.
14758f0484fSRodney W. GrimesThis makes the two part address format convenient
14858f0484fSRodney W. Grimesfor specifying Class A network addresses as
14958f0484fSRodney W. Grimes.Dq Li net.host .
15058f0484fSRodney W. Grimes.Pp
15158f0484fSRodney W. GrimesWhen only one part is given, the value is stored
15258f0484fSRodney W. Grimesdirectly in the network address without any byte
15358f0484fSRodney W. Grimesrearrangement.
15458f0484fSRodney W. Grimes.Pp
15558f0484fSRodney W. GrimesAll numbers supplied as
15658f0484fSRodney W. Grimes.Dq parts
15758f0484fSRodney W. Grimesin a
15858f0484fSRodney W. Grimes.Ql  \&.
15958f0484fSRodney W. Grimesnotation
16058f0484fSRodney W. Grimesmay be decimal, octal, or hexadecimal, as specified
16158f0484fSRodney W. Grimesin the C language (i.e., a leading 0x or 0X implies
16258f0484fSRodney W. Grimeshexadecimal; otherwise, a leading 0 implies octal;
16358f0484fSRodney W. Grimesotherwise, the number is interpreted as decimal).
164538e8768SGarrett Wollman.Pp
165538e8768SGarrett WollmanThe
166538e8768SGarrett Wollman.Fn inet_aton
167538e8768SGarrett Wollmanand
168538e8768SGarrett Wollman.Fn inet_ntoa
169538e8768SGarrett Wollmanfunctions are semi-deprecated in favor of the
170538e8768SGarrett Wollman.Xr addr2ascii 3
171538e8768SGarrett Wollmanfamily.  However, since those functions are not yet widely implemented,
172538e8768SGarrett Wollmanportable programs cannot rely on their presence and will continue
173538e8768SGarrett Wollmanto use the
174538e8768SGarrett Wollman.Xr inet 3
175538e8768SGarrett Wollmanfunctions for some time.
17658f0484fSRodney W. Grimes.Sh DIAGNOSTICS
17758f0484fSRodney W. GrimesThe constant
17858f0484fSRodney W. Grimes.Dv INADDR_NONE
17958f0484fSRodney W. Grimesis returned by
18058f0484fSRodney W. Grimes.Fn inet_addr
18158f0484fSRodney W. Grimesand
18258f0484fSRodney W. Grimes.Fn inet_network
18358f0484fSRodney W. Grimesfor malformed requests.
18458f0484fSRodney W. Grimes.Sh SEE ALSO
185538e8768SGarrett Wollman.Xr addr2ascii 3 ,
18658f0484fSRodney W. Grimes.Xr gethostbyname 3 ,
18758f0484fSRodney W. Grimes.Xr getnetent 3 ,
18858f0484fSRodney W. Grimes.Xr hosts 5 ,
18913608f66SWolfram Schneider.Xr networks 5
19058f0484fSRodney W. Grimes.Sh HISTORY
19158f0484fSRodney W. GrimesThese
19258f0484fSRodney W. Grimesfunctions appeared in
19358f0484fSRodney W. Grimes.Bx 4.2 .
19458f0484fSRodney W. Grimes.Sh BUGS
19558f0484fSRodney W. GrimesThe value
19658f0484fSRodney W. Grimes.Dv INADDR_NONE
19758f0484fSRodney W. Grimes(0xffffffff) is a valid broadcast address, but
19858f0484fSRodney W. Grimes.Fn inet_addr
19958f0484fSRodney W. Grimescannot return that value without indicating failure.
20058f0484fSRodney W. GrimesThe newer
20158f0484fSRodney W. Grimes.Fn inet_aton
20258f0484fSRodney W. Grimesfunction does not share this problem.
20358f0484fSRodney W. GrimesThe problem of host byte ordering versus network byte ordering is
20458f0484fSRodney W. Grimesconfusing.
20558f0484fSRodney W. GrimesThe string returned by
20658f0484fSRodney W. Grimes.Fn inet_ntoa
20758f0484fSRodney W. Grimesresides in a static memory area.
20858f0484fSRodney W. Grimes.Pp
20958f0484fSRodney W. GrimesInet_addr should return a
21058f0484fSRodney W. Grimes.Fa struct in_addr .
211