Libc-594.9.4.tar.gz

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

diff --git a/net/inet.3 b/net/inet.3
index c65d1dc1a03e16e880ce58a2f186a4238afaa125..b15ab0161e058f12de4be92cad906d2decf8ffec 100644 (file)
--- a/net/inet.3
+++ b/net/inet.3
@@ -30,51 +30,73 @@
 .\" SUCH DAMAGE.
 .\"
 .\"     From: @(#)inet.3       8.1 (Berkeley) 6/4/93
-.\" $FreeBSD: src/lib/libc/net/inet.3,v 1.19 2001/10/01 16:08:55 ru Exp $
+.\" $FreeBSD: src/lib/libc/net/inet.3,v 1.29 2004/07/02 23:52:11 ru Exp $
 .\"
-.Dd June 17, 1996
+.Dd June 14, 2004
 .Dt INET 3
 .Os
 .Sh NAME
-.Nm inet_aton ,
 .Nm inet_addr ,
+.Nm inet_aton ,
+.Nm inet_lnaof ,
+.Nm inet_makeaddr ,
+.Nm inet_netof ,
 .Nm inet_network ,
 .Nm inet_ntoa ,
 .Nm inet_ntop ,
-.Nm inet_pton ,
-.Nm inet_makeaddr ,
-.Nm inet_lnaof ,
-.Nm inet_netof
+.Nm inet_pton
 .Nd Internet address manipulation routines
 .Sh LIBRARY
 .Lb libc
 .Sh SYNOPSIS
-.In sys/types.h
-.In sys/socket.h
-.In netinet/in.h
 .In arpa/inet.h
+.Ft in_addr_t
+.Fo inet_addr
+.Fa "const char *cp"
+.Fc
 .Ft int
-.Fn inet_aton "const char *cp" "struct in_addr *pin"
+.Fo inet_aton
+.Fa "const char *cp"
+.Fa "struct in_addr *pin"
+.Fc
+.Ft in_addr_t
+.Fo inet_lnaof
+.Fa "struct in_addr in"
+.Fc
+.Ft struct in_addr
+.Fo inet_makeaddr
+.Fa "in_addr_t net"
+.Fa "in_addr_t lna"
+.Fc
 .Ft in_addr_t
-.Fn inet_addr "const char *cp"
+.Fo inet_netof
+.Fa "struct in_addr in"
+.Fc
 .Ft in_addr_t
-.Fn inet_network "const char *cp"
+.Fo inet_network
+.Fa "const char *cp"
+.Fc
 .Ft char *
-.Fn inet_ntoa "struct in_addr in"
+.Fo inet_ntoa
+.Fa "struct in_addr in"
+.Fc
 .Ft const char *
-.Fn inet_ntop "int af" "const void *src" "char *dst" "size_t size"
+.Fo inet_ntop
+.Fa "int af"
+.Fa "const void *restrict src"
+.Fa "char *restrict dst"
+.Fa "socklen_t size"
+.Fc
 .Ft int
-.Fn inet_pton "int af" "const char *src" "void *dst"
-.Ft struct in_addr
-.Fn inet_makeaddr "in_addr_t net" "in_addr_t lna"
-.Ft in_addr_t
-.Fn inet_lnaof "struct in_addr in"
-.Ft in_addr_t
-.Fn inet_netof "struct in_addr in"
+.Fo inet_pton
+.Fa "int af"
+.Fa "const char *restrict src"
+.Fa "void *restrict dst"
+.Fc
 .Sh DESCRIPTION
 The routines
 .Fn inet_aton ,
-.Fn inet_addr
+.Fn inet_addr ,
 and
 .Fn inet_network
 interpret character strings representing
@@ -114,10 +136,17 @@ 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 .
 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.
@@ -132,11 +161,13 @@ takes an Internet address and returns an
 .Tn ASCII
 string representing the address in
 .Ql .\&
-notation.  The routine
+notation.
+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
@@ -162,7 +193,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
@@ -208,7 +240,8 @@ 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,
+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
@@ -221,12 +254,36 @@ 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 EAFNOSUPPORT
+.Fa *src
+was not an
+.Dv AF_INET
+or
+.Dv AF_INET6
+family address.
+.It Bq Er ENOSPC
+.Fa size
+was not large enough to store the presentation form of the address.
+.El
+.Sh LEGACY SYNOPSIS
+.Fd #include <sys/types.h>
+.Fd #include <sys/socket.h>
+.Fd #include <netinet/in.h>
+.Fd #include <arpa/inet.h>
+.Pp
+These include files are necessary for all functions.
 .Sh SEE ALSO
 .Xr addr2ascii 3 ,
 .Xr byteorder 3 ,
 .Xr gethostbyname 3 ,
 .Xr getnetent 3 ,
 .Xr inet_net 3 ,
+.Xr compat 5 ,
 .Xr hosts 5 ,
 .Xr networks 5
 .Rs
@@ -245,7 +302,7 @@ functions conform to
 Note that
 .Fn inet_pton
 does not accept 1-, 2-, or 3-part dotted addresses; all four parts
-must be specified.
+must be specified and are interpreted only as decimal values.
 This is a narrower input set than that accepted by
 .Fn inet_aton .
 .Sh HISTORY