summaryrefslogtreecommitdiff
path: root/src/lib/libc/net/inet_ntop.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libc/net/inet_ntop.3')
-rw-r--r--src/lib/libc/net/inet_ntop.3213
1 files changed, 0 insertions, 213 deletions
diff --git a/src/lib/libc/net/inet_ntop.3 b/src/lib/libc/net/inet_ntop.3
deleted file mode 100644
index e5c1c574f8..0000000000
--- a/src/lib/libc/net/inet_ntop.3
+++ /dev/null
@@ -1,213 +0,0 @@
1.\" $OpenBSD: inet_ntop.3,v 1.6 2022/09/11 06:38:10 jmc Exp $
2.\" $NetBSD: inet.3,v 1.7 1997/06/18 02:25:24 lukem Exp $
3.\"
4.\" Copyright (c) 1983, 1990, 1991, 1993
5.\" The Regents of the University of California. All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\" notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\" notice, this list of conditions and the following disclaimer in the
14.\" documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the University nor the names of its contributors
16.\" may be used to endorse or promote products derived from this software
17.\" without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" @(#)inet.3 8.1 (Berkeley) 6/4/93
32.\"
33.Dd $Mdocdate: September 11 2022 $
34.Dt INET_NTOP 3
35.Os
36.Sh NAME
37.Nm inet_ntop ,
38.Nm inet_pton
39.Nd convert Internet addresses between presentation and network formats
40.Sh SYNOPSIS
41.In sys/socket.h
42.In arpa/inet.h
43.Ft const char *
44.Fn inet_ntop "int af" "const void * restrict src" "char * restrict dst" "socklen_t size"
45.Ft int
46.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst"
47.Sh DESCRIPTION
48The
49.Fn inet_pton
50function converts a presentation format address (that is, printable form
51as held in a character string) to network format (usually a
52.Vt struct in_addr
53or some other internal binary representation, in network byte order).
54It returns 1 if the address was valid for the specified address family;
550 if the address wasn't parseable in the specified address family; or \-1
56if some system error occurred (in which case
57.Va errno
58will have been set).
59This function is presently valid for
60.Dv AF_INET
61and
62.Dv AF_INET6 .
63.Pp
64The function
65.Fn inet_ntop
66converts an address from network format to presentation format.
67It returns
68.Dv NULL
69if a system
70error occurs (in which case,
71.Va errno
72will have been set), or it returns a pointer to the destination string.
73.Pp
74All Internet addresses are returned in network
75order (bytes ordered from left to right).
76.Sh INTERNET ADDRESSES (IP VERSION 4)
77Values must be specified using the standard dot notation:
78.Bd -literal -offset indent
79a.b.c.d
80.Ed
81.Pp
82All four parts must be decimal numbers between 0 and 255, inclusive,
83and are assigned, from left to right,
84to the four bytes of an Internet address.
85Note that when an Internet address is viewed as a 32-bit integer
86quantity on a system that uses little-endian byte order
87(such as AMD64 or ARM processors)
88the bytes referred to above appear as
89.Dq Li d.c.b.a .
90That is, little-endian bytes are ordered from right to left.
91.Sh INTERNET ADDRESSES (IP VERSION 6)
92In order to support scoped IPv6 addresses,
93.Xr getaddrinfo 3
94and
95.Xr getnameinfo 3
96are recommended rather than the functions presented here.
97.Pp
98The presentation format of an IPv6 address is given in RFC 4291:
99.Pp
100There are three conventional forms for representing IPv6 addresses as
101text strings:
102.Bl -enum
103.It
104The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the
105hexadecimal values of the eight 16-bit pieces of the address.
106Examples:
107.Bd -literal -offset indent
108FEDC:BA98:7654:3210:FEDC:BA98:7654:3210
1091080:0:0:0:8:800:200C:417A
110.Ed
111.Pp
112Note that it is not necessary to write the leading zeros in an
113individual field, but there must be at least one numeral in
114every field (except for the case described in 2.).
115.It
116Due to the method of allocating certain styles of IPv6
117addresses, it will be common for addresses to contain long
118strings of zero bits.
119In order to make writing addresses
120containing zero bits easier, a special syntax is available to
121compress the zeros.
122The use of
123.Dq \&:\&:
124indicates multiple groups
125of 16 bits of zeros.
126The
127.Dq \&:\&:
128can only appear once in an
129address.
130The
131.Dq \&:\&:
132can also be used to compress the leading and/or trailing zeros in an address.
133.Pp
134For example the following addresses:
135.Bd -literal -offset indent
1361080:0:0:0:8:800:200C:417A a unicast address
137FF01:0:0:0:0:0:0:43 a multicast address
1380:0:0:0:0:0:0:1 the loopback address
1390:0:0:0:0:0:0:0 the unspecified addresses
140.Ed
141.Pp
142may be represented as:
143.Bd -literal -offset indent
1441080::8:800:200C:417A a unicast address
145FF01::43 a multicast address
146::1 the loopback address
147:: the unspecified addresses
148.Ed
149.It
150An alternative form that is sometimes more convenient when
151dealing with a mixed environment of IPv4 and IPv6 nodes is
152x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values
153of the six high-order 16-bit pieces of the address, and the 'd's
154are the decimal values of the four low-order 8-bit pieces of the
155address (standard IPv4 representation).
156Examples:
157.Bd -literal -offset indent
1580:0:0:0:0:0:13.1.68.3
1590:0:0:0:0:FFFF:129.144.52.38
160.Ed
161.Pp
162or in compressed form:
163.Bd -literal -offset indent
164::13.1.68.3
165::FFFF:129.144.52.38
166.Ed
167.El
168.Sh SEE ALSO
169.Xr gethostbyname 3 ,
170.Xr inet_addr 3 ,
171.Xr inet_net_ntop 3 ,
172.Xr hosts 5
173.Sh STANDARDS
174The
175.Nm inet_ntop
176and
177.Nm inet_pton
178functions conform to the IETF IPv6 BSD API and address formatting
179specifications, as well as
180.St -p1003.1-2008 .
181.Sh HISTORY
182The
183.Nm inet_pton
184and
185.Nm inet_ntop
186functions appeared in BIND 4.9.4.
187.Sh CAVEATS
188Note that
189.Nm inet_pton
190does not accept 1-, 2-, or 3-part dotted addresses;
191all four parts must be specified and must be in decimal
192(and not octal or hexadecimal).
193This is a narrower input set than that accepted by
194.Nm inet_aton .
195.Pp
196.Rs
197.%A R. Gilligan
198.%A S. Thomson
199.%A J. Bound
200.%A J. McCann
201.%A W. Stevens
202.%D February 2003
203.%R RFC 3493
204.%T Basic Socket Interface Extensions for IPv6
205.Re
206.Pp
207.Rs
208.%A R. Hinden
209.%A S. Deering
210.%D February 2006
211.%R RFC 4291
212.%T IP Version 6 Addressing Architecture
213.Re