Remove PARAMETERS section. Different bad. Kjell bad.

Add references to sockaddr_storage.

1 files changed, 31 insertions, 21 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