socket.7: Document 'sockaddr' and 'sockaddr_storage' types

Reported-by: YOSHIFUJI Hideaki <yoshfuji@linux-ipv6.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

1 files changed, 49 insertions, 1 deletions

diff --git a/man7/socket.7 b/man7/socket.7
index 5872f3940d..5515a74e01 100644
--- a/man7/socket.7
+++ b/man7/socket.7
@@ -43,7 +43,7 @@
 .\"		commit 3bdc0eba0b8b47797f4a76e377dd8360f317450f
 .\"		Author: Ben Greear <greearb@candelatech.com>
 .\"
-.TH SOCKET 7 2012-07-07 Linux "Linux Programmer's Manual"
+.TH SOCKET 7 2012-12-15 Linux "Linux Programmer's Manual"
 .SH NAME
 socket \- Linux socket interface
 .SH SYNOPSIS
@@ -219,6 +219,54 @@ must be installed via
 See the
 .I Signals
 discussion below.
+.SS Socket address structures
+Each socket domain has its own format for socket addresses,
+with a domain-specific address structure.
+Each of these structures begins with an
+integer "family" field (typed as
+.IR sa_family_t )
+that indicates the type of the address structure.
+This allows
+the various system calls (e.g.,
+.BR connect (2),
+.BR bind (2),
+.BR accept (2),
+.BR getsockname (2),
+.BR getpeername (2)),
+which are generic to all socket domains,
+to determine the domain of a particular socket address.
+
+To allow any type of socket address to be passed to
+interfaces in the sockets API,
+the type
+.IR "struct sockaddr"
+is defined.
+The purpose of this type is purely to allow casting of 
+domain-specific socket address types to a "generic" type,
+so as to avoid compiler warnings about type mismatches in 
+calls to the sockets API.
+
+In addition, the sockets API provides the data type
+.IR "struct sockaddr_storage".
+This type
+is suitable to accommodate all supported domain-specific socket
+address structures; it is large enough and is aligned properly.
+(In particular, it is large enough to hold 
+IPv6 socket addresses.)
+The structure includes the following field, which can be used to identify
+the type of socket address actually stored in the structure:
+
+.in +4n
+.nf
+    sa_family_t ss_family;
+.fi
+.in
+
+The 
+.I sockaddr_storage
+structure is useful in programs that must handle socket addresses
+in a generic way
+(e.g., programs that must deal with both IPv4 and IPv6 socket addresses).
 .SS Socket Options
 These socket options can be set by using
 .BR setsockopt (2)