1.\" $OpenBSD: inet_ntop.3,v 1.2 2014/05/09 06:38:27 guenther 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: May 9 2014 $ 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 arpa/inet.h 42.Ft const char * 43.Fn inet_ntop "int af" "const void * restrict src" "char * restrict dst" "socklen_t size" 44.Ft int 45.Fn inet_pton "int af" "const char * restrict src" "void * restrict dst" 46.Sh DESCRIPTION 47The 48.Fn inet_pton 49function converts a presentation format address (that is, printable form 50as held in a character string) to network format (usually a 51.Li struct in_addr 52or some other internal binary representation, in network byte order). 53It returns 1 if the address was valid for the specified address family; 540 if the address wasn't parseable in the specified address family; or \-1 55if some system error occurred (in which case 56.Va errno 57will have been set). 58This function is presently valid for 59.Dv AF_INET 60and 61.Dv AF_INET6 . 62.Pp 63The function 64.Fn inet_ntop 65converts an address from network format to presentation format. 66It returns 67.Dv NULL 68if a system 69error occurs (in which case, 70.Va errno 71will have been set), or it returns a pointer to the destination string. 72.Pp 73All Internet addresses are returned in network 74order (bytes ordered from left to right). 75.Sh INTERNET ADDRESSES (IP VERSION 4) 76Values must be specified using the standard dot notation: 77.Bd -literal -offset indent 78a.b.c.d 79.Ed 80.Pp 81All four parts must be decimal numbers between 0 and 255, inclusive, 82and are assigned, from left to right, 83to the four bytes of an Internet address. 84Note that when an Internet address is viewed as a 32-bit integer 85quantity on a system that uses little-endian byte order 86(such as the Intel 386, 486 and Pentium processors) 87the bytes referred to above appear as 88.Dq Li d.c.b.a . 89That is, little-endian bytes are ordered from right to left. 90.Sh INTERNET ADDRESSES (IP VERSION 6) 91In order to support scoped IPv6 addresses, 92.Xr getaddrinfo 3 93and 94.Xr getnameinfo 3 95are recommended rather than the functions presented here. 96.Pp 97The presentation format of an IPv6 address is given in RFC 4291: 98.Pp 99There are three conventional forms for representing IPv6 addresses as 100text strings: 101.Bl -enum 102.It 103The preferred form is x:x:x:x:x:x:x:x, where the 'x's are the 104hexadecimal values of the eight 16-bit pieces of the address. 105Examples: 106.Bd -literal -offset indent 107FEDC:BA98:7654:3210:FEDC:BA98:7654:3210 1081080:0:0:0:8:800:200C:417A 109.Ed 110.Pp 111Note that it is not necessary to write the leading zeros in an 112individual field, but there must be at least one numeral in 113every field (except for the case described in 2.). 114.It 115Due to the method of allocating certain styles of IPv6 116addresses, it will be common for addresses to contain long 117strings of zero bits. 118In order to make writing addresses 119containing zero bits easier, a special syntax is available to 120compress the zeros. 121The use of 122.Dq \&:\&: 123indicates multiple groups 124of 16 bits of zeros. 125The 126.Dq \&:\&: 127can only appear once in an 128address. 129The 130.Dq \&:\&: 131can also be used to compress the leading and/or trailing zeros in an address. 132.Pp 133For example the following addresses: 134.Bd -literal -offset indent 1351080:0:0:0:8:800:200C:417A a unicast address 136FF01:0:0:0:0:0:0:43 a multicast address 1370:0:0:0:0:0:0:1 the loopback address 1380:0:0:0:0:0:0:0 the unspecified addresses 139.Ed 140.Pp 141may be represented as: 142.Bd -literal -offset indent 1431080::8:800:200C:417A a unicast address 144FF01::43 a multicast address 145::1 the loopback address 146:: the unspecified addresses 147.Ed 148.It 149An alternative form that is sometimes more convenient when 150dealing with a mixed environment of IPv4 and IPv6 nodes is 151x:x:x:x:x:x:d.d.d.d, where the 'x's are the hexadecimal values 152of the six high-order 16-bit pieces of the address, and the 'd's 153are the decimal values of the four low-order 8-bit pieces of the 154address (standard IPv4 representation). 155Examples: 156.Bd -literal -offset indent 1570:0:0:0:0:0:13.1.68.3 1580:0:0:0:0:FFFF:129.144.52.38 159.Ed 160.Pp 161or in compressed form: 162.Bd -literal -offset indent 163::13.1.68.3 164::FFFF:129.144.52.38 165.Ed 166.El 167.Sh SEE ALSO 168.Xr gethostbyname 3 , 169.Xr inet_addr 3 , 170.Xr inet_net 3 , 171.Xr hosts 5 172.Sh STANDARDS 173The 174.Nm inet_ntop 175and 176.Nm inet_pton 177functions conform to the IETF IPv6 BSD API and address formatting 178specifications, as well as 179.St -p1003.1-2008 . 180.Sh HISTORY 181The 182.Nm inet_pton 183and 184.Nm inet_ntop 185functions appeared in BIND 4.9.4. 186.Sh CAVEATS 187Note that 188.Nm inet_pton 189does not accept 1-, 2-, or 3-part dotted addresses; 190all four parts must be specified and must be in decimal 191(and not octal or hexadecimal). 192This is a narrower input set than that accepted by 193.Nm inet_aton . 194.Pp 195.Rs 196.%A R. Gilligan 197.%A S. Thomson 198.%A J. Bound 199.%A J. McCann 200.%A W. Stevens 201.%D February 2003 202.%R RFC 3493 203.%T Basic Socket Interface Extensions for IPv6 204.Re 205.Pp 206.Rs 207.%A R. Hinden 208.%A S. Deering 209.%D February 2006 210.%R RFC 4291 211.%T IP Version 6 Addressing Architecture 212.Re 213