xref: /freebsd/lib/libc/net/inet.3 (revision 2da24fa6e933aade9b459a78537f4a86bba323a7)
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
337f3dea24SPeter Wemm.\" $FreeBSD$
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 ,
4389482e46SYoshinobu Inoue.Nm inet_ntop ,
4489482e46SYoshinobu Inoue.Nm inet_pton ,
4558f0484fSRodney W. Grimes.Nm inet_makeaddr ,
4658f0484fSRodney W. Grimes.Nm inet_lnaof ,
4758f0484fSRodney W. Grimes.Nm inet_netof
4858f0484fSRodney W. Grimes.Nd Internet address manipulation routines
4925bb73e0SAlexey Zelkin.Sh LIBRARY
5025bb73e0SAlexey Zelkin.Lb libc
5158f0484fSRodney W. Grimes.Sh SYNOPSIS
52433671e3SBruce Evans.Fd #include <sys/types.h>
5358f0484fSRodney W. Grimes.Fd #include <sys/socket.h>
5458f0484fSRodney W. Grimes.Fd #include <netinet/in.h>
5558f0484fSRodney W. Grimes.Fd #include <arpa/inet.h>
5658f0484fSRodney W. Grimes.Ft int
57433671e3SBruce Evans.Fn inet_aton "const char *cp" "struct in_addr *pin"
582da24fa6SHajimu UMEMOTO.Ft in_addr_t
59433671e3SBruce Evans.Fn inet_addr "const char *cp"
602da24fa6SHajimu UMEMOTO.Ft in_addr_t
61433671e3SBruce Evans.Fn inet_network "const char *cp"
6258f0484fSRodney W. Grimes.Ft char *
6358f0484fSRodney W. Grimes.Fn inet_ntoa "struct in_addr in"
6489482e46SYoshinobu Inoue.Ft const char *
6589482e46SYoshinobu Inoue.Fn inet_ntop "int af" "const void *src" "char *dst" "size_t size"
6689482e46SYoshinobu Inoue.Ft int
6789482e46SYoshinobu Inoue.Fn inet_pton "int af" "const char *src" "void *dst"
6858f0484fSRodney W. Grimes.Ft struct in_addr
692da24fa6SHajimu UMEMOTO.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna"
702da24fa6SHajimu UMEMOTO.Ft in_addr_t
7158f0484fSRodney W. Grimes.Fn inet_lnaof "struct in_addr in"
722da24fa6SHajimu UMEMOTO.Ft in_addr_t
7358f0484fSRodney W. Grimes.Fn inet_netof "struct in_addr in"
7458f0484fSRodney W. Grimes.Sh DESCRIPTION
7558f0484fSRodney W. GrimesThe routines
7658f0484fSRodney W. Grimes.Fn inet_aton ,
7758f0484fSRodney W. Grimes.Fn inet_addr
7858f0484fSRodney W. Grimesand
7958f0484fSRodney W. Grimes.Fn inet_network
8058f0484fSRodney W. Grimesinterpret character strings representing
8158f0484fSRodney W. Grimesnumbers expressed in the Internet standard
8242635956SRuslan Ermilov.Ql .\&
8358f0484fSRodney W. Grimesnotation.
8489482e46SYoshinobu Inoue.Pp
8589482e46SYoshinobu InoueThe
8689482e46SYoshinobu Inoue.Fn inet_pton
8789482e46SYoshinobu Inouefunction converts a presentation format address (that is, printable form
8889482e46SYoshinobu Inoueas held in a character string) to network format (usually a
8989482e46SYoshinobu Inoue.Ft struct in_addr
9089482e46SYoshinobu Inoueor some other internal binary representation, in network byte order).
9189482e46SYoshinobu InoueIt returns 1 if the address was valid for the specified address family, or
9289482e46SYoshinobu Inoue0 if the address wasn't parseable in the specified address family, or -1
9389482e46SYoshinobu Inoueif some system error occurred (in which case
9489482e46SYoshinobu Inoue.Va errno
9589482e46SYoshinobu Inouewill have been set).
9689482e46SYoshinobu InoueThis function is presently valid for
9789482e46SYoshinobu Inoue.Dv AF_INET
9889482e46SYoshinobu Inoueand
9989482e46SYoshinobu Inoue.Dv AF_INET6 .
10089482e46SYoshinobu Inoue.Pp
10158f0484fSRodney W. GrimesThe
10258f0484fSRodney W. Grimes.Fn inet_aton
10358f0484fSRodney W. Grimesroutine interprets the specified character string as an Internet address,
10458f0484fSRodney W. Grimesplacing the address into the structure provided.
10558f0484fSRodney W. GrimesIt returns 1 if the string was successfully interpreted,
10658f0484fSRodney W. Grimesor 0 if the string is invalid.
10758f0484fSRodney W. GrimesThe
10858f0484fSRodney W. Grimes.Fn inet_addr
10958f0484fSRodney W. Grimesand
11058f0484fSRodney W. Grimes.Fn inet_network
11158f0484fSRodney W. Grimesfunctions return numbers suitable for use
11258f0484fSRodney W. Grimesas Internet addresses and Internet network
11358f0484fSRodney W. Grimesnumbers, respectively.
11489482e46SYoshinobu Inoue.Pp
11589482e46SYoshinobu InoueThe function
11689482e46SYoshinobu Inoue.Fn inet_ntop
11789482e46SYoshinobu Inoueconverts an address from network format (usually a
11889482e46SYoshinobu Inoue.Ft struct in_addr
11989482e46SYoshinobu Inoueor some other binary form, in network byte order) to presentation format
12089482e46SYoshinobu Inoue(suitable for external display purposes).
12189482e46SYoshinobu InoueIt returns NULL if a system error occurs (in which case,
12289482e46SYoshinobu Inoue.Va errno
12389482e46SYoshinobu Inouewill have been set), or it returns a pointer to the destination string.
12489482e46SYoshinobu InoueThis function is presently valid for
12589482e46SYoshinobu Inoue.Dv AF_INET
12689482e46SYoshinobu Inoueand
12789482e46SYoshinobu Inoue.Dv AF_INET6 .
12889482e46SYoshinobu Inoue.Pp
12958f0484fSRodney W. GrimesThe routine
13058f0484fSRodney W. Grimes.Fn inet_ntoa
13158f0484fSRodney W. Grimestakes an Internet address and returns an
13258f0484fSRodney W. Grimes.Tn ASCII
13358f0484fSRodney W. Grimesstring representing the address in
13442635956SRuslan Ermilov.Ql .\&
13558f0484fSRodney W. Grimesnotation.  The routine
13658f0484fSRodney W. Grimes.Fn inet_makeaddr
13758f0484fSRodney W. Grimestakes an Internet network number and a local
13858f0484fSRodney W. Grimesnetwork address and constructs an Internet address
13958f0484fSRodney W. Grimesfrom it.  The routines
14058f0484fSRodney W. Grimes.Fn inet_netof
14158f0484fSRodney W. Grimesand
14258f0484fSRodney W. Grimes.Fn inet_lnaof
14358f0484fSRodney W. Grimesbreak apart Internet host addresses, returning
14458f0484fSRodney W. Grimesthe network number and local network address part,
14558f0484fSRodney W. Grimesrespectively.
14658f0484fSRodney W. Grimes.Pp
14758f0484fSRodney W. GrimesAll Internet addresses are returned in network
14858f0484fSRodney W. Grimesorder (bytes ordered from left to right).
14958f0484fSRodney W. GrimesAll network numbers and local address parts are
15058f0484fSRodney W. Grimesreturned as machine format integer values.
15158f0484fSRodney W. Grimes.Sh INTERNET ADDRESSES
15258f0484fSRodney W. GrimesValues specified using the
15342635956SRuslan Ermilov.Ql .\&
15458f0484fSRodney W. Grimesnotation take one
15558f0484fSRodney W. Grimesof the following forms:
15658f0484fSRodney W. Grimes.Bd -literal -offset indent
15758f0484fSRodney W. Grimesa.b.c.d
15858f0484fSRodney W. Grimesa.b.c
15958f0484fSRodney W. Grimesa.b
16058f0484fSRodney W. Grimesa
16158f0484fSRodney W. Grimes.Ed
16258f0484fSRodney W. Grimes.Pp
16358f0484fSRodney W. GrimesWhen four parts are specified, each is interpreted
16458f0484fSRodney W. Grimesas a byte of data and assigned, from left to right,
16558f0484fSRodney W. Grimesto the four bytes of an Internet address.  Note
16658f0484fSRodney W. Grimesthat when an Internet address is viewed as a 32-bit
16758f0484fSRodney W. Grimesinteger quantity on the
16858f0484fSRodney W. Grimes.Tn VAX
16958f0484fSRodney W. Grimesthe bytes referred to
17058f0484fSRodney W. Grimesabove appear as
17158f0484fSRodney W. Grimes.Dq Li d.c.b.a .
17258f0484fSRodney W. GrimesThat is,
17358f0484fSRodney W. Grimes.Tn VAX
17458f0484fSRodney W. Grimesbytes are
17558f0484fSRodney W. Grimesordered from right to left.
17658f0484fSRodney W. Grimes.Pp
17758f0484fSRodney W. GrimesWhen a three part address is specified, the last
17858f0484fSRodney W. Grimespart is interpreted as a 16-bit quantity and placed
17958f0484fSRodney W. Grimesin the right-most two bytes of the network address.
18058f0484fSRodney W. GrimesThis makes the three part address format convenient
18158f0484fSRodney W. Grimesfor specifying Class B network addresses as
18258f0484fSRodney W. Grimes.Dq Li 128.net.host .
18358f0484fSRodney W. Grimes.Pp
18458f0484fSRodney W. GrimesWhen a two part address is supplied, the last part
18558f0484fSRodney W. Grimesis interpreted as a 24-bit quantity and placed in
18658f0484fSRodney W. Grimesthe right most three bytes of the network address.
18758f0484fSRodney W. GrimesThis makes the two part address format convenient
18858f0484fSRodney W. Grimesfor specifying Class A network addresses as
18958f0484fSRodney W. Grimes.Dq Li net.host .
19058f0484fSRodney W. Grimes.Pp
19158f0484fSRodney W. GrimesWhen only one part is given, the value is stored
19258f0484fSRodney W. Grimesdirectly in the network address without any byte
19358f0484fSRodney W. Grimesrearrangement.
19458f0484fSRodney W. Grimes.Pp
19558f0484fSRodney W. GrimesAll numbers supplied as
19658f0484fSRodney W. Grimes.Dq parts
19758f0484fSRodney W. Grimesin a
19842635956SRuslan Ermilov.Ql .\&
19958f0484fSRodney W. Grimesnotation
20058f0484fSRodney W. Grimesmay be decimal, octal, or hexadecimal, as specified
20158f0484fSRodney W. Grimesin the C language (i.e., a leading 0x or 0X implies
20258f0484fSRodney W. Grimeshexadecimal; otherwise, a leading 0 implies octal;
20358f0484fSRodney W. Grimesotherwise, the number is interpreted as decimal).
204538e8768SGarrett Wollman.Pp
205538e8768SGarrett WollmanThe
206538e8768SGarrett Wollman.Fn inet_aton
207538e8768SGarrett Wollmanand
208538e8768SGarrett Wollman.Fn inet_ntoa
209538e8768SGarrett Wollmanfunctions are semi-deprecated in favor of the
210538e8768SGarrett Wollman.Xr addr2ascii 3
211538e8768SGarrett Wollmanfamily.  However, since those functions are not yet widely implemented,
212538e8768SGarrett Wollmanportable programs cannot rely on their presence and will continue
213538e8768SGarrett Wollmanto use the
214538e8768SGarrett Wollman.Xr inet 3
215538e8768SGarrett Wollmanfunctions for some time.
21658f0484fSRodney W. Grimes.Sh DIAGNOSTICS
21758f0484fSRodney W. GrimesThe constant
21858f0484fSRodney W. Grimes.Dv INADDR_NONE
21958f0484fSRodney W. Grimesis returned by
22058f0484fSRodney W. Grimes.Fn inet_addr
22158f0484fSRodney W. Grimesand
22258f0484fSRodney W. Grimes.Fn inet_network
22358f0484fSRodney W. Grimesfor malformed requests.
22458f0484fSRodney W. Grimes.Sh SEE ALSO
225538e8768SGarrett Wollman.Xr addr2ascii 3 ,
22658f0484fSRodney W. Grimes.Xr gethostbyname 3 ,
22758f0484fSRodney W. Grimes.Xr getnetent 3 ,
22858f0484fSRodney W. Grimes.Xr hosts 5 ,
22913608f66SWolfram Schneider.Xr networks 5
23089482e46SYoshinobu Inoue.Rs
23189482e46SYoshinobu Inoue.%R RFC
23289482e46SYoshinobu Inoue.%N 2373
23389482e46SYoshinobu Inoue.%D July 1998
23489482e46SYoshinobu Inoue.%T "IP Version 6 Addressing Architecture"
23589482e46SYoshinobu Inoue.Re
23689482e46SYoshinobu Inoue.Sh STANDARDS
23789482e46SYoshinobu InoueThe
238563f6bdeSRuslan Ermilov.Fn inet_ntop
23989482e46SYoshinobu Inoueand
240563f6bdeSRuslan Ermilov.Fn inet_pton
24189482e46SYoshinobu Inouefunctions conform to
24289482e46SYoshinobu Inoue.St -xns5.2d2.0 .
24389482e46SYoshinobu InoueNote that
244563f6bdeSRuslan Ermilov.Fn inet_pton
24589482e46SYoshinobu Inouedoes not accept 1-, 2-, or 3-part  dotted addresses; all four parts
24689482e46SYoshinobu Inouemust be specified.
24789482e46SYoshinobu InoueThis is a narrower input set than that accepted by
248563f6bdeSRuslan Ermilov.Fn inet_aton .
24958f0484fSRodney W. Grimes.Sh HISTORY
25058f0484fSRodney W. GrimesThese
25158f0484fSRodney W. Grimesfunctions appeared in
25258f0484fSRodney W. Grimes.Bx 4.2 .
25358f0484fSRodney W. Grimes.Sh BUGS
25458f0484fSRodney W. GrimesThe value
25558f0484fSRodney W. Grimes.Dv INADDR_NONE
25658f0484fSRodney W. Grimes(0xffffffff) is a valid broadcast address, but
25758f0484fSRodney W. Grimes.Fn inet_addr
25858f0484fSRodney W. Grimescannot return that value without indicating failure.
25958f0484fSRodney W. GrimesThe newer
26058f0484fSRodney W. Grimes.Fn inet_aton
26158f0484fSRodney W. Grimesfunction does not share this problem.
26258f0484fSRodney W. GrimesThe problem of host byte ordering versus network byte ordering is
26358f0484fSRodney W. Grimesconfusing.
26458f0484fSRodney W. GrimesThe string returned by
26558f0484fSRodney W. Grimes.Fn inet_ntoa
26658f0484fSRodney W. Grimesresides in a static memory area.
26758f0484fSRodney W. Grimes.Pp
26858f0484fSRodney W. GrimesInet_addr should return a
26958f0484fSRodney W. Grimes.Fa struct in_addr .
270