xref: /freebsd/lib/libc/net/inet.3 (revision 90aad5d3e44d137ce80d2ec257de07c7c1367bd3)
1.\" Copyright (c) 1983, 1990, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. Neither the name of the University nor the names of its contributors
13.\"    may be used to endorse or promote products derived from this software
14.\"    without specific prior written permission.
15.\"
16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26.\" SUCH DAMAGE.
27.\"
28.\"     From: @(#)inet.3	8.1 (Berkeley) 6/4/93
29.\"
30.Dd November 9, 2021
31.Dt INET 3
32.Os
33.Sh NAME
34.Nm inet_aton ,
35.Nm inet_addr ,
36.Nm inet_network ,
37.Nm inet_ntoa ,
38.Nm inet_ntoa_r ,
39.Nm inet_ntop ,
40.Nm inet_pton ,
41.Nm inet_makeaddr ,
42.Nm inet_lnaof ,
43.Nm inet_netof
44.Nd Internet address manipulation routines
45.Sh LIBRARY
46.Lb libc
47.Sh SYNOPSIS
48.In sys/types.h
49.In sys/socket.h
50.In netinet/in.h
51.In arpa/inet.h
52.Ft int
53.Fn inet_aton "const char *cp" "struct in_addr *pin"
54.Ft in_addr_t
55.Fn inet_addr "const char *cp"
56.Ft in_addr_t
57.Fn inet_network "const char *cp"
58.Ft char *
59.Fn inet_ntoa "struct in_addr in"
60.Ft char *
61.Fo inet_ntoa_r
62.Fa "struct in_addr in"
63.Fa "char *buf"
64.Fa "socklen_t size"
65.Fc
66.Ft const char *
67.Fo inet_ntop
68.Fa "int af"
69.Fa "const void * restrict src"
70.Fa "char * restrict dst"
71.Fa "socklen_t size"
72.Fc
73.Ft int
74.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst"
75.Ft struct in_addr
76.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna"
77.Ft in_addr_t
78.Fn inet_lnaof "struct in_addr in"
79.Ft in_addr_t
80.Fn inet_netof "struct in_addr in"
81.Sh DESCRIPTION
82The routines
83.Fn inet_aton ,
84.Fn inet_addr
85and
86.Fn inet_network
87interpret character strings representing
88numbers expressed in the Internet standard
89.Ql .\&
90notation.
91.Pp
92The
93.Fn inet_pton
94function converts a presentation format address (that is, printable form
95as held in a character string) to network format (usually a
96.Ft struct in_addr
97or some other internal binary representation, in network byte order).
98It returns 1 if the address was valid for the specified address family, or
990 if the address was not parseable in the specified address family, or -1
100if some system error occurred (in which case
101.Va errno
102will have been set).
103This function is presently valid for
104.Dv AF_INET
105and
106.Dv AF_INET6 .
107.Pp
108The
109.Fn inet_aton
110routine interprets the specified character string as an Internet address,
111placing the address into the structure provided.
112It returns 1 if the string was successfully interpreted,
113or 0 if the string is invalid.
114The
115.Fn inet_addr
116and
117.Fn inet_network
118functions return numbers suitable for use
119as Internet addresses and Internet network
120numbers, respectively.
121.Pp
122The function
123.Fn inet_ntop
124converts an address
125.Fa *src
126from network format
127(usually a
128.Ft struct in_addr
129or some other binary form, in network byte order) to presentation format
130(suitable for external display purposes).
131The
132.Fa size
133argument specifies the size, in bytes, of the buffer
134.Fa *dst .
135.Dv INET_ADDRSTRLEN
136and
137.Dv INET6_ADDRSTRLEN
138define the maximum size required to convert an address of the respective
139type.
140It returns NULL if a system error occurs (in which case,
141.Va errno
142will have been set), or it returns a pointer to the destination string.
143This function is presently valid for
144.Dv AF_INET
145and
146.Dv AF_INET6 .
147.Pp
148The routine
149.Fn inet_ntoa
150takes an Internet address and returns an
151.Tn ASCII
152string representing the address in
153.Ql .\&
154notation.
155The routine
156.Fn inet_ntoa_r
157is the reentrant version of
158.Fn inet_ntoa .
159The deprecated routine
160.Fn inet_makeaddr
161takes an Internet network number and a local
162host address on that network, and constructs an Internet address
163from it.
164It should only be assumed to work for historical class A/B/C networks.
165The deprecated routines
166.Fn inet_netof
167and
168.Fn inet_lnaof
169break apart Internet host addresses, returning
170the network number and local host address part,
171respectively,
172assuming the historical class A/B/C network masks.
173.Pp
174All Internet addresses are returned in network
175order (bytes ordered from left to right).
176All network numbers and local address parts are
177returned as machine byte order integer values.
178.Sh INTERNET ADDRESSES
179Values specified using the
180.Ql .\&
181notation take one
182of the following forms:
183.Bd -literal -offset indent
184a.b.c.d
185a.b.c
186a.b
187a
188.Ed
189.Pp
190When four parts are specified, each is interpreted
191as a byte of data and assigned, from left to right,
192to the four bytes of an Internet address.
193.Pp
194When a three part address is specified, the last
195part is interpreted as a 16-bit quantity and placed
196in the least significant two bytes of the network address.
197.Pp
198When a two part address is supplied, the last part
199is interpreted as a 24-bit quantity and placed in
200the least significant three bytes of the network address.
201.Pp
202When only one part is given, the value is stored
203directly in the network address without any byte
204rearrangement.
205.Pp
206All numbers supplied as
207.Dq parts
208in a
209.Ql .\&
210notation
211may be decimal, octal, or hexadecimal, as specified
212in the C language (i.e., a leading 0x or 0X implies
213hexadecimal; otherwise, a leading 0 implies octal;
214otherwise, the number is interpreted as decimal).
215.Sh DIAGNOSTICS
216The constant
217.Dv INADDR_NONE
218is returned by
219.Fn inet_addr
220and
221.Fn inet_network
222for malformed requests.
223.Sh ERRORS
224The
225.Fn inet_ntop
226call fails if:
227.Bl -tag -width Er
228.It Bq Er ENOSPC
229.Fa size
230was not large enough to store the presentation form of the address.
231.It Bq Er EAFNOSUPPORT
232.Fa *src
233was not an
234.Dv AF_INET
235or
236.Dv AF_INET6
237family address.
238.El
239.Sh SEE ALSO
240.Xr byteorder 3 ,
241.Xr getaddrinfo 3 ,
242.Xr gethostbyname 3 ,
243.Xr getnameinfo 3 ,
244.Xr getnetent 3 ,
245.Xr inet_net 3 ,
246.Xr hosts 5 ,
247.Xr networks 5
248.Rs
249.%R RFC
250.%N 2373
251.%D July 1998
252.%T "IP Version 6 Addressing Architecture"
253.Re
254.Sh STANDARDS
255The
256.Fn inet_ntop
257and
258.Fn inet_pton
259functions conform to
260.St -xns5.2 .
261Note that
262.Fn inet_pton
263does not accept 1-, 2-, or 3-part dotted addresses; all four parts
264must be specified and are interpreted only as decimal values.
265This is a narrower input set than that accepted by
266.Fn inet_aton .
267.Sh HISTORY
268These
269functions appeared in
270.Bx 4.2 .
271.Sh BUGS
272The value
273.Dv INADDR_NONE
274(0xffffffff) is a valid broadcast address, but
275.Fn inet_addr
276cannot return that value without indicating failure.
277The newer
278.Fn inet_aton
279function does not share this problem.
280The problem of host byte ordering versus network byte ordering is
281confusing.
282The string returned by
283.Fn inet_ntoa
284resides in a static memory area.
285.Pp
286The
287.Fn inet_addr
288function should return a
289.Fa struct in_addr .
290