[src/trunk]: src/lib/libc/sys more description from openbsd.

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

details:   https://anonhg.NetBSD.org/src/rev/6195515440e3
branches:  trunk
changeset: 535164:6195515440e3
user:      yamt <yamt%NetBSD.org@localhost>
date:      Sun Aug 11 12:22:48 2002 +0000

description:
more description from openbsd.

diffstat:

 lib/libc/sys/getsockname.2 |  87 +++++++++++++++++++++++++++++++++++++++------
 1 files changed, 75 insertions(+), 12 deletions(-)

diffs (112 lines):

diff -r b9e23d2ad62d -r 6195515440e3 lib/libc/sys/getsockname.2
--- a/lib/libc/sys/getsockname.2        Sun Aug 11 12:16:27 2002 +0000
+++ b/lib/libc/sys/getsockname.2        Sun Aug 11 12:22:48 2002 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: getsockname.2,v 1.16 2002/02/08 01:28:18 ross Exp $
+.\"    $NetBSD: getsockname.2,v 1.17 2002/08/11 12:22:48 yamt Exp $
 .\"
 .\" Copyright (c) 1983, 1991, 1993
 .\"    The Regents of the University of California.  All rights reserved.
@@ -33,7 +33,7 @@
 .\"
 .\"     @(#)getsockname.2      8.1 (Berkeley) 6/4/93
 .\"
-.Dd October 22, 2001
+.Dd August 11, 2002
 .Dt GETSOCKNAME 2
 .Os
 .Sh NAME
@@ -46,20 +46,83 @@
 .Ft int
 .Fn getsockname "int s" "struct sockaddr * restrict name" "socklen_t * restrict namelen"
 .Sh DESCRIPTION
-The
+.Fn getsockname
+returns the locally bound address information for a specified socket.
+.Pp
+Common uses of this function are as follows:
+.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
-system call returns the current
+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
-for the specified socket.
-The
+points to a
+.Li 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
+.Li sockaddr_in
+(IPv4) or
+.Li sockaddr_in6
+(IPv6), cast to a (struct sockaddr *).
+.Pp
+For greater portability (such as newer protocol families) the new
+structure sockaddr_storage exists.
+.Li 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
-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.
+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
+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
+On success,
+.Fn getsockname
+returns a 0, 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).
-.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