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 214