Updated man pages to be useful. Include description of typical uses.

2 files changed, 101 insertions, 23 deletions

diff --git a/lib/libc/sys/getpeername.2 b/lib/libc/sys/getpeername.2
index 7ce4aea75fd..a82f8609ca2 100644
--- a/lib/libc/sys/getpeername.2
+++ b/lib/libc/sys/getpeername.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: getpeername.2,v 1.10 1999/06/29 14:10:00 aaron Exp $
+.\"	$OpenBSD: getpeername.2,v 1.11 1999/07/21 05:39:55 kjell Exp $
 .\"	$NetBSD: getpeername.2,v 1.6 1995/10/12 15:40:56 jtc Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -34,7 +34,7 @@
 .\"
 .\"     @(#)getpeername.2	8.1 (Berkeley) 6/4/93
 .\"
-.Dd February 15, 1999
+.Dd July 17, 1999
 .Dt GETPEERNAME 2
 .Os
 .Sh NAME
@@ -45,23 +45,51 @@
 .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 name of the peer connected to
+returns the address information of the peer connected to
 socket
 .Fa s .
-The
+.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,
+.Fn getpeername
+is used to determine the connecting client's IP address.
+.Pp
+If the local socket address is required, the
+.Xr getsockname 2
+function should be used instead.
+.Pp
+If
+.Fa name
+does not point to enough space to hold the entire socket address, the
+result will be truncated to
 .Fa namelen
-parameter should be initialized to indicate
-the amount of space pointed to by
-.Fa name .
-On return it contains the actual size of the name
-returned (in bytes).
-The name is truncated if the buffer provided is too small.
+bytes.
 .Sh RETURN VALUES
-A 0 is returned if the call succeeds, \-1 if it fails.
+If the call succeeds, a 0 is returned and
+.Fa namelen
+is set to the actual size of the socket address returned in
+.Fa name .
+Otherwise, errno is set and a value of \-1 is returned.
 .Sh ERRORS
-The call succeeds unless:
+On failure, errno is set to one of the following:
 .Bl -tag -width Er
 .It Bq Er EBADF
 The argument
diff --git a/lib/libc/sys/getsockname.2 b/lib/libc/sys/getsockname.2
index 229cd0a437f..d3d4b03e013 100644
--- a/lib/libc/sys/getsockname.2
+++ b/lib/libc/sys/getsockname.2
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: getsockname.2,v 1.10 1999/06/29 14:10:02 aaron Exp $
+.\"	$OpenBSD: getsockname.2,v 1.11 1999/07/21 05:39:55 kjell Exp $
 .\"	$NetBSD: getsockname.2,v 1.6 1995/10/12 15:41:00 jtc Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
@@ -34,7 +34,7 @@
 .\"
 .\"     @(#)getsockname.2	8.1 (Berkeley) 6/4/93
 .\"
-.Dd February 15, 1999
+.Dd July 17, 1999
 .Dt GETSOCKNAME 2
 .Os
 .Sh NAME
@@ -45,21 +45,69 @@
 .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 current
+returns the locally bound address information for a specified socket.
+.Pp
+This function is useful in a number of circumstances. For instance:
+.Bl -bullet
+.It
+When
+.Xr bind 2
+is called with a port number of 0 (indicating the kernel should pick
+an ephemeral port)
+.Fn getsockname
+is used to retrieve the kernel-assigned port number.
+.It
+When a process calls
+.Xr bind 2
+on a wildcard IP address,
+.Fn getsockname
+is used to retrieve the local IP address for the connection.
+.It
+When a function wishes to know the address family of a socket,
+.Fn getsockname
+can be used.
+.El
+.Pp
+If the address of the destination socket for a given socket connection is
+needed, the
+.Xr getpeername 2
+function should be used instead.
+.Pp
+If
 .Fa name
-for the specified socket.  The
+does not point to enough space to hold the entire socket address, the
+result will be truncated to
 .Fa namelen
-parameter should be initialized to indicate
-the amount of space pointed to by
-.Fa name .
-On return it contains the actual size of the name
-returned (in bytes).
+bytes.
+.Pp
 .Sh RETURN VALUES
-A 0 is returned if the call succeeds, \-1 if it fails.
+On success,
+.Fn getsockname
+returns a 0, and
+.Fa namelen
+is set to the actual size of the socket address returned in
+.Fa name .
+Otherwise, errno is set, and a value of \-1 is returned.
 .Sh ERRORS
-The call succeeds unless:
+If
+.Fn getsockname
+fails, errno is set to one of the following:
 .Bl -tag -width Er
 .It Bq Er EBADF
 The argument
@@ -79,7 +127,9 @@ parameter points to memory not in a valid part of the
 process address space.
 .El
 .Sh SEE ALSO
+.Xr accept 2 ,
 .Xr bind 2 ,
+.Xr getpeername 2 ,
 .Xr socket 2
 .Sh BUGS
 Names bound to sockets in the UNIX domain are inaccessible;