more description from openbsd.

lib/libc/sys/getsockname.2

@@ -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
-system call returns the current
+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
+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
-.Fa name .
-On return it contains the actual size of the name returned (in
-bytes).
+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
-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,
+.Va errno
+is set, and a value of \-1 is returned.
 .Sh ERRORS
 The call succeeds unless:
 .Bl -tag -width Er