Libc-763.13.tar.gz

[apple/libc.git] / net / FreeBSD / inet.3

diff --git a/net/FreeBSD/inet.3 b/net/FreeBSD/inet.3
index 06f6a850321f1f13aa5f895d28c587ec987c68f2..1211e5332e736d6419a7dfa69c6aedcb0d33d194 100644 (file)
--- a/net/FreeBSD/inet.3
+++ b/net/FreeBSD/inet.3
@@ -9,10 +9,6 @@
 .\" 2. Redistributions in binary form must reproduce the above copyright
 .\"    notice, this list of conditions and the following disclaimer in the
 .\"    documentation and/or other materials provided with the distribution.
-.\" 3. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"    This product includes software developed by the University of
-.\"    California, Berkeley and its contributors.
 .\" 4. Neither the name of the University nor the names of its contributors
 .\"    may be used to endorse or promote products derived from this software
 .\"    without specific prior written permission.
@@ -30,9 +26,9 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)inet.3       8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/net/inet.3,v 1.25 2002/09/06 11:23:49 tjr Exp $
+.\" $FreeBSD: src/lib/libc/net/inet.3,v 1.36 2007/06/14 07:13:28 delphij Exp $
 .\"
-.Dd June 17, 1996
+.Dd June 14, 2007
 .Dt INET 3
 .Os
 .Sh NAME
@@ -40,6 +36,7 @@
 .Nm inet_addr ,
 .Nm inet_network ,
 .Nm inet_ntoa ,
+.Nm inet_ntoa_r ,
 .Nm inet_ntop ,
 .Nm inet_pton ,
 .Nm inet_makeaddr ,
@@ -61,6 +58,12 @@
 .Fn inet_network "const char *cp"
 .Ft char *
 .Fn inet_ntoa "struct in_addr in"
+.Ft char *
+.Fo inet_ntoa_r
+.Fa "struct in_addr in"
+.Fa "char *buf"
+.Fa "socklen_t size"
+.Fc
 .Ft const char *
 .Fo inet_ntop
 .Fa "int af"
@@ -94,7 +97,7 @@ as held in a character string) to network format (usually a
 .Ft struct in_addr
 or some other internal binary representation, in network byte order).
 It returns 1 if the address was valid for the specified address family, or
-0 if the address wasn't parseable in the specified address family, or -1
+0 if the address was not parseable in the specified address family, or -1
 if some system error occurred (in which case
 .Va errno
 will have been set).
@@ -119,10 +122,22 @@ numbers, respectively.
 .Pp
 The function
 .Fn inet_ntop
-converts an address from network format (usually a
+converts an address
+.Fa *src
+from network format
+(usually a
 .Ft struct in_addr
 or some other binary form, in network byte order) to presentation format
 (suitable for external display purposes).
+The
+.Fa size
+argument specifies the size, in bytes, of the buffer
+.Fa *dst .
+.Dv INET_ADDRSTRLEN
+and
+.Dv INET6_ADDRSTRLEN
+define the maximum size required to convert an address of the respective
+type.
 It returns NULL if a system error occurs (in which case,
 .Va errno
 will have been set), or it returns a pointer to the destination string.
@@ -137,11 +152,17 @@ takes an Internet address and returns an
 .Tn ASCII
 string representing the address in
 .Ql .\&
-notation.  The routine
+notation.
+The routine
+.Fn inet_ntoa_r
+is the reentrant version of
+.Fn inet_ntoa .
+The routine
 .Fn inet_makeaddr
 takes an Internet network number and a local
 network address and constructs an Internet address
-from it.  The routines
+from it.
+The routines
 .Fn inet_netof
 and
 .Fn inet_lnaof
@@ -167,7 +188,8 @@ a
 .Pp
 When four parts are specified, each is interpreted
 as a byte of data and assigned, from left to right,
-to the four bytes of an Internet address.  Note
+to the four bytes of an Internet address.
+Note
 that when an Internet address is viewed as a 32-bit
 integer quantity on the
 .Tn VAX
@@ -206,18 +228,6 @@ may be decimal, octal, or hexadecimal, as specified
 in the C language (i.e., a leading 0x or 0X implies
 hexadecimal; otherwise, a leading 0 implies octal;
 otherwise, the number is interpreted as decimal).
-.Pp
-The
-.Fn inet_aton
-and
-.Fn inet_ntoa
-functions are semi-deprecated in favor of the
-.Xr addr2ascii 3
-family.  However, since those functions are not yet widely implemented,
-portable programs cannot rely on their presence and will continue
-to use the
-.Xr inet 3
-functions for some time.
 .Sh DIAGNOSTICS
 The constant
 .Dv INADDR_NONE
@@ -226,10 +236,27 @@ is returned by
 and
 .Fn inet_network
 for malformed requests.
+.Sh ERRORS
+The
+.Fn inet_ntop
+call fails if:
+.Bl -tag -width Er
+.It Bq Er ENOSPC
+.Fa size
+was not large enough to store the presentation form of the address.
+.It Bq Er EAFNOSUPPORT
+.Fa *src
+was not an
+.Dv AF_INET
+or
+.Dv AF_INET6
+family address.
+.El
 .Sh SEE ALSO
-.Xr addr2ascii 3 ,
 .Xr byteorder 3 ,
+.Xr getaddrinfo 3 ,
 .Xr gethostbyname 3 ,
+.Xr getnameinfo 3 ,
 .Xr getnetent 3 ,
 .Xr inet_net 3 ,
 .Xr hosts 5 ,
@@ -272,5 +299,7 @@ The string returned by
 .Fn inet_ntoa
 resides in a static memory area.
 .Pp
-Inet_addr should return a
+The
+.Fn inet_addr
+function should return a
 .Fa struct in_addr .