.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "INET_NTOP" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" inet_ntop 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
inet_ntop, inet_pton \- convert IPv4 and IPv6 addresses between binary
and text form
.SH SYNOPSIS
.LP
\fB#include <arpa/inet.h>
.br
.sp
const char *inet_ntop(int\fP \fIaf\fP\fB, const void *restrict\fP
\fIsrc\fP\fB,
.br
\ \ \ \ \ \  char *restrict\fP \fIdst\fP\fB, socklen_t\fP \fIsize\fP\fB);
.br
int inet_pton(int\fP \fIaf\fP\fB, const char *restrict\fP \fIsrc\fP\fB,
void *restrict\fP \fIdst\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIinet_ntop\fP() function shall convert a numeric address into
a text string suitable for presentation. The \fIaf\fP
argument shall specify the family of the address. This can be AF_INET
\ or AF_INET6.  The \fIsrc\fP argument points to a buffer holding
an IPv4 address if the \fIaf\fP argument is AF_INET,
\ or an IPv6 address if the \fIaf\fP argument is AF_INET6;  the
address must be in network byte order. The \fIdst\fP argument points
to a buffer where the function stores the resulting text
string; it shall not be NULL. The \fIsize\fP argument specifies the
size of this buffer, which shall be large enough to hold the
text string (INET_ADDRSTRLEN characters for IPv4,  INET6_ADDRSTRLEN
characters for IPv6). 
.LP
The \fIinet_pton\fP() function shall convert an address in its standard
text presentation form into its numeric binary form.
The \fIaf\fP argument shall specify the family of the address. The
AF_INET  and AF_INET6
address families shall be supported. The \fIsrc\fP argument points
to the string being passed in. The \fIdst\fP argument points to a
buffer into which the function stores the numeric address; this
shall be large enough to hold the numeric address (32 bits for AF_INET,
\ 128 bits for AF_INET6). 
.LP
If the \fIaf\fP argument of \fIinet_pton\fP() is AF_INET, the \fIsrc\fP
string shall be in the standard IPv4 dotted-decimal
form:
.sp
.RS
.nf

\fBddd.ddd.ddd.ddd
\fP
.fi
.RE
.LP
where \fB"ddd"\fP is a one to three digit decimal number between 0
and 255 (see \fIinet_addr\fP()). The \fIinet_pton\fP() function does
not accept other formats (such as the octal
numbers, hexadecimal numbers, and fewer than four numbers that \fIinet_addr\fP()
accepts).
.LP
If the \fIaf\fP argument of \fIinet_pton\fP() is AF_INET6, the \fIsrc\fP
string shall be in one of the following standard IPv6
text forms:
.IP " 1." 4
The preferred form is \fB"x:x:x:x:x:x:x:x"\fP, where the \fB'x'\fP
s are the hexadecimal values of the eight 16-bit
pieces of the address. Leading zeros in individual fields can be omitted,
but there shall be at least one numeral in every
field.
.LP
.IP " 2." 4
A string of contiguous zero fields in the preferred form can be shown
as \fB"::"\fP . The \fB"::"\fP can only appear once
in an address. Unspecified addresses ( \fB"0:0:0:0:0:0:0:0"\fP ) may
be represented simply as \fB"::"\fP .
.LP
.IP " 3." 4
A third form that is sometimes more convenient when dealing with a
mixed environment of IPv4 and IPv6 nodes is
\fB"x:x:x:x:x:x:d.d.d.d"\fP, where the \fB'x'\fP s are the hexadecimal
values of the six high-order 16-bit pieces of the
address, and the \fB'd'\fP s are the decimal values of the four low-order
8-bit pieces of the address (standard IPv4
representation).
.LP
.TP 7
\fBNote:\fP
A more extensive description of the standard representations of IPv6
addresses can be found in RFC\ 2373.
.sp
.SH RETURN VALUE
.LP
The \fIinet_ntop\fP() function shall return a pointer to the buffer
containing the text string if the conversion succeeds, and
NULL otherwise, and set \fIerrno\fP to indicate the error.
.LP
The \fIinet_pton\fP() function shall return 1 if the conversion succeeds,
with the address pointed to by \fIdst\fP in network
byte order. It shall return 0 if the input is not a valid IPv4 dotted-decimal
string  or a valid
IPv6 address string,  or -1 with \fIerrno\fP set to [EAFNOSUPPORT]
if the \fIaf\fP argument is unknown.
.SH ERRORS
.LP
The \fIinet_ntop\fP() and \fIinet_pton\fP() functions shall fail if:
.TP 7
.B EAFNOSUPPORT
.sp
The \fIaf\fP argument is invalid.
.TP 7
.B ENOSPC
The size of the \fIinet_ntop\fP() result buffer is inadequate.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
The Base Definitions volume of IEEE\ Std\ 1003.1-2001, \fI<arpa/inet.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .