[src/trunk]: src/lib/libc/sys - include typical uses.

[yamt <yamt%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/5347f39e3e47
branches:  trunk
changeset: 535157:5347f39e3e47
user:      yamt <yamt%NetBSD.org@localhost>
date:      Sun Aug 11 12:04:25 2002 +0000

description:
- include typical uses.
from openbsd.

diffstat:

 lib/libc/sys/getpeername.2 |  65 ++++++++++++++++++++++++++++++++++++++-------
 1 files changed, 55 insertions(+), 10 deletions(-)

diffs (88 lines):

diff -r b84d69cefcc9 -r 5347f39e3e47 lib/libc/sys/getpeername.2
--- a/lib/libc/sys/getpeername.2        Sun Aug 11 11:57:44 2002 +0000
+++ b/lib/libc/sys/getpeername.2        Sun Aug 11 12:04:25 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getpeername.2,v 1.13 2002/02/08 01:28:17 ross Exp $
+.\"    $NetBSD: getpeername.2,v 1.14 2002/08/11 12:04:25 yamt Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -33,7 +33,7 @@
 .\"
 .\"     @(#)getpeername.2      8.1 (Berkeley) 6/4/93
 .\"
-.Dd October 22, 2001
+.Dd August 11, 2002
 .Dt GETPEERNAME 2
 .Os
 .Sh NAME
@@ -50,16 +50,61 @@
 returns the name of the peer connected to
 socket
 .Fa s .
-The
+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
+.Fn getpeername
+takes three parameters:
+.Pp
+.Fa s
+Contains the file descriptor of the socket whose peer should be looked up.
+.Pp
+.Fa name
+Points to a
+.Li 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
+.Li sockaddr_in
+(IPv4) or
+.Li sockaddr_in6
+(IPv6), cast to a (struct sockaddr *).
+.Pp
+For greater portability, especially with the newer protocol families, the new
+.Li struct sockaddr_storage
+should be used.
+.Li 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
-parameter should be initialized to indicate
-the amount of space pointed to by
+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
+If
+.Fa name
+does not point to enough space to hold the entire socket address, the
+result will be truncated to
+.Fa namelen
+bytes.
+.Sh RETURN VALUES
+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 .
-On return it contains the actual size of the name
-returned (in bytes).
-The name is truncated if the buffer provided is too small.
-.Sh RETURN VALUES
-A 0 is returned if the call succeeds, -1 if it fails.
+Otherwise,
+.Va errno
+is set and a value of \-1 is returned.
 .Sh ERRORS
 The call succeeds unless:
 .Bl -tag -width Er