mirror of https://github.com/mkerrisk/man-pages
144 lines
5.0 KiB
Plaintext
144 lines
5.0 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "INET_NTOP" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" inet_ntop
|
|
.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 .
|