Remove PARAMETERS section. Different bad. Kjell bad.

Add references to sockaddr_storage.

2 files changed, 58 insertions, 37 deletions

diff --git a/lib/libc/sys/getpeername.2 b/lib/libc/sys/getpeername.2
index a82f8609ca2..1ce4b1c0d7d 100644
--- a/lib/libc/sys/getpeername.2
+++ b/lib/libc/sys/getpeername.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: getpeername.2,v 1.11 1999/07/21 05:39:55 kjell Exp $
+.\"	$OpenBSD: getpeername.2,v 1.12 1999/07/21 07:18:26 kjell Exp $
 .\"	$NetBSD: getpeername.2,v 1.6 1995/10/12 15:40:56 jtc Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -45,34 +45,44 @@
 .Fd #include <sys/socket.h>
 .Ft int
 .Fn getpeername "int s" "struct sockaddr *name" "socklen_t *namelen"
-.Sh PARAMETERS
-.Bl -tag -width namelen
-.It s
-Contains the file descriptor of the socket who's peer should be looked up.
-.It name
-Points to a sockaddr structure that will hold the address information
-for the connected peer. The format of this socket depends on the protocol family in use. See
-.Xr socket 2
-for details.
-.It namelen
-Indicates the amount of space pointed to by
-.Fa name ,
-in bytes.
 .Sh DESCRIPTION
 .Fn getpeername
 returns the address information of the peer connected to
 socket
 .Fa s .
-.Pp
-.Fn getpeername
-is useful in a variety of circumstances. The most common
-use occurs when a process inherits an open socket, such as when
-.Xr inetd 8
-forks and execs a TCP server. In this scenario,
+One common
+use occurs when a process inherits an open socket, such as
+TCP servers forked from
+.Xr inetd 8 .
+In this scenario,
 .Fn getpeername
 is used to determine the connecting client's IP address.
 .Pp
-If the local socket address is required, the
+.Fn getpeername
+takes three parameters:
+.Pp
+.Fa s
+Contains the file descriptor of the socket who's peer should be looked up.
+.Pp
+.Fa name
+Points to a sockaddr structure that will hold the address information
+for the connected peer.
+Normal use requires one to use a structure
+specific to the protocol family in use, such as sockaddr_in (IPv4)
+or sockaddr_in6 (IPv6), cast to a (struct sockaddr *).
+.Pp
+For greater portability, especially with the newer protocol families, the new
+struct sockaddr_storage should be used. sockaddr_storage is
+large enough to hold any of the other sockaddr_* variants.
+On return, it can be cast to the correct sockaddr type,
+based the protocol family contained in its ss_family field.
+.Pp
+.Fa namelen
+Indicates the amount of space pointed to by
+.Fa name ,
+in bytes.
+.Pp
+If address information for the local end of the socket is required, the
 .Xr getsockname 2
 function should be used instead.
 .Pp
diff --git a/lib/libc/sys/getsockname.2 b/lib/libc/sys/getsockname.2
index d3d4b03e013..3d966cab30e 100644
--- a/lib/libc/sys/getsockname.2
+++ b/lib/libc/sys/getsockname.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: getsockname.2,v 1.11 1999/07/21 05:39:55 kjell Exp $
+.\"	$OpenBSD: getsockname.2,v 1.12 1999/07/21 07:18:27 kjell Exp $
 .\"	$NetBSD: getsockname.2,v 1.6 1995/10/12 15:41:00 jtc Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -45,25 +45,11 @@
 .Fd #include <sys/socket.h>
 .Ft int
 .Fn getsockname "int s" "struct sockaddr *name" "socklen_t *namelen"
-.Sh PARAMETERS
-.Bl -tag -width namelen
-.It s
-Contains the file desriptor for the socket to be looked up.
-.It name
-Points to a sockaddr structure to hold the resulting address information.
-The format of this socket depends on the protocol family in use. See
-.Xr socket 2
-for details.
-.It namelen
-Indicates the amount of space pointed to by
-.Fa name ,
-in bytes.
-.El
 .Sh DESCRIPTION
 .Fn getsockname
 returns the locally bound address information for a specified socket.
 .Pp
-This function is useful in a number of circumstances. For instance:
+Common uses of this function are as follows:
 .Bl -bullet
 .It
 When
@@ -84,6 +70,31 @@ When a function wishes to know the address family of a socket,
 can be used.
 .El
 .Pp
+.Fn getsockname
+takes three parameters:
+.Pp
+.Fa s ,
+Contains the file desriptor for the socket to be looked up.
+.Pp
+.Fa name
+points to a sockaddr structure which will hold the resulting
+address information.  Normal use requires one to use a structure
+specific to the protocol family in use, such as sockaddr_in (IPv4)
+or sockaddr_in6 (IPv6), cast to a (struct sockaddr *).
+.Pp
+For greater portability (such as newer protocol families) the new
+structure sockaddr_storage exists. sockaddr_storage is
+large enough to hold any of the other sockaddr_* variants.
+On return, it should be cast to the correct sockaddr type,
+according to the current protocol family.
+.Pp
+.Fa namelen
+Indicates the amount of space pointed to by
+.Fa name ,
+in bytes. Upon return,
+.Fa namelen
+is set to the actual size of the returned address information.
+.Pp
 If the address of the destination socket for a given socket connection is
 needed, the
 .Xr getpeername 2