(scm_getsockopt, scm_setsockopt): Update docstrings from posix.texi.

diff --git a/libguile/socket.c b/libguile/socket.c
index 6dfc800..d18cb2c 100644 (file)
--- a/libguile/socket.c
+++ b/libguile/socket.c
@@ -462,14 +462,50 @@ SCM_DEFINE (scm_socketpair, "socketpair", 3, 0, 0,
 
 SCM_DEFINE (scm_getsockopt, "getsockopt", 3, 0, 0,
             (SCM sock, SCM level, SCM optname),
-           "Return the value of a particular socket option for the socket\n"
-           "port @var{sock}.  @var{level} is an integer code for type of\n"
-           "option being requested, e.g., @code{SOL_SOCKET} for\n"
-           "socket-level options.  @var{optname} is an integer code for the\n"
-           "option required and should be specified using one of the\n"
-           "symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.\n\n"
-           "The returned value is typically an integer but @code{SO_LINGER}\n"
-           "returns a pair of integers.")
+           "Return an option value from socket port @var{sock}.\n"
+           "\n"
+           "@var{level} is an integer specifying a protocol layer, either\n"
+           "@code{SOL_SOCKET} for socket level options, or a protocol\n"
+           "number from the @code{IPPROTO} constants or @code{getprotoent}\n"
+           "(@pxref{Network Databases}).\n"
+           "\n"
+           "@defvar SOL_SOCKET\n"
+           "@defvarx IPPROTO_IP\n"
+           "@defvarx IPPROTO_TCP\n"
+           "@defvarx IPPROTO_UDP\n"
+           "@end defvar\n"
+           "\n"
+           "@var{optname} is an integer specifying an option within the\n"
+           "protocol layer.\n"
+           "\n"
+           "For @code{SOL_SOCKET} level the following @var{optname}s are\n"
+           "defined (when provided by the system).  For their meaning see\n"
+           "@ref{Socket-Level Options,,, libc, The GNU C Library Reference\n"
+           "Manual}, or @command{man 7 socket}.\n"
+           "\n"
+           "@defvar SO_DEBUG\n"
+           "@defvarx SO_REUSEADDR\n"
+           "@defvarx SO_STYLE\n"
+           "@defvarx SO_TYPE\n"
+           "@defvarx SO_ERROR\n"
+           "@defvarx SO_DONTROUTE\n"
+           "@defvarx SO_BROADCAST\n"
+           "@defvarx SO_SNDBUF\n"
+           "@defvarx SO_RCVBUF\n"
+           "@defvarx SO_KEEPALIVE\n"
+           "@defvarx SO_OOBINLINE\n"
+           "@defvarx SO_NO_CHECK\n"
+           "@defvarx SO_PRIORITY\n"
+           "The value returned is an integer.\n"
+           "@end defvar\n"
+           "\n"
+           "@defvar SO_LINGER\n"
+           "The @var{value} returned is a pair of integers\n"
+           "@code{(@var{ENABLE} . @var{TIMEOUT})}.  On old systems without\n"
+           "timeout support (ie.@: without @code{struct linger}), only\n"
+           "@var{ENABLE} has an effect but the value in Guile is always a\n"
+           "pair.\n"
+           "@end defvar")
 #define FUNC_NAME s_scm_getsockopt
 {
   int fd;
@@ -528,16 +564,69 @@ SCM_DEFINE (scm_getsockopt, "getsockopt", 3, 0, 0,
 
 SCM_DEFINE (scm_setsockopt, "setsockopt", 4, 0, 0,
             (SCM sock, SCM level, SCM optname, SCM value),
-           "Set the value of a particular socket option for the socket\n"
-           "port @var{sock}.  @var{level} is an integer code for type of option\n"
-           "being set, e.g., @code{SOL_SOCKET} for socket-level options.\n"
-           "@var{optname} is an\n"
-           "integer code for the option to set and should be specified using one of\n"
-           "the symbols @code{SO_DEBUG}, @code{SO_REUSEADDR} etc.\n"
-           "@var{value} is the value to which the option should be set.  For\n"
-           "most options this must be an integer, but for @code{SO_LINGER} it must\n"
-           "be a pair.\n\n"
-           "The return value is unspecified.")
+           "Set an option on socket port @var{sock}.  The return value is\n"
+           "unspecified.\n"
+           "\n"
+           "@var{level} is an integer specifying a protocol layer, either\n"
+           "@code{SOL_SOCKET} for socket level options, or a protocol\n"
+           "number from the @code{IPPROTO} constants or @code{getprotoent}\n"
+           "(@pxref{Network Databases}).\n"
+           "\n"
+           "@defvar SOL_SOCKET\n"
+           "@defvarx IPPROTO_IP\n"
+           "@defvarx IPPROTO_TCP\n"
+           "@defvarx IPPROTO_UDP\n"
+           "@end defvar\n"
+           "\n"
+           "@var{optname} is an integer specifying an option within the\n"
+           "protocol layer.\n"
+           "\n"
+           "For @code{SOL_SOCKET} level the following @var{optname}s are\n"
+           "defined (when provided by the system).  For their meaning see\n"
+           "@ref{Socket-Level Options,,, libc, The GNU C Library Reference\n"
+           "Manual}, or @command{man 7 socket}.\n"
+           "\n"
+           "@defvar SO_DEBUG\n"
+           "@defvarx SO_REUSEADDR\n"
+           "@defvarx SO_STYLE\n"
+           "@defvarx SO_TYPE\n"
+           "@defvarx SO_ERROR\n"
+           "@defvarx SO_DONTROUTE\n"
+           "@defvarx SO_BROADCAST\n"
+           "@defvarx SO_SNDBUF\n"
+           "@defvarx SO_RCVBUF\n"
+           "@defvarx SO_KEEPALIVE\n"
+           "@defvarx SO_OOBINLINE\n"
+           "@defvarx SO_NO_CHECK\n"
+           "@defvarx SO_PRIORITY\n"
+           "@var{value} is an integer.\n"
+           "@end defvar\n"
+           "\n"
+           "@defvar SO_LINGER\n"
+           "@var{value} is a pair of integers @code{(@var{ENABLE}\n"
+           ". @var{TIMEOUT})}.  On old systems without timeout support\n"
+           "(ie.@: without @code{struct linger}), only @var{ENABLE} has an\n"
+           "effect but the value in Guile is always a pair.\n"
+           "@end defvar\n"
+           "\n"
+           "@c  Note that we refer only to ``man ip'' here.  On GNU/Linux it's\n"
+           "@c  ``man 7 ip'' but on NetBSD it's ``man 4 ip''.\n"
+           "@c \n"
+           "For IP level (@code{IPPROTO_IP}) the following @var{optname}s\n"
+           "are defined (when provided by the system).  See @command{man\n"
+           "ip} for what they mean.\n"
+           "\n"
+           "@defvar IP_ADD_MEMBERSHIP\n"
+           "@defvarx IP_DROP_MEMBERSHIP\n"
+           "These can be used only with @code{setsockopt}, not\n"
+           "@code{getsockopt}.  @var{value} is a pair\n"
+           "@code{(@var{MULTIADDR} . @var{INTERFACEADDR})} of IPv4\n"
+           "addresses (@pxref{Network Address Conversion}).\n"
+           "@var{MULTIADDR} is a multicast address to be added to or\n"
+           "dropped from the interface @var{INTERFACEADDR}.\n"
+           "@var{INTERFACEADDR} can be @code{INADDR_ANY} to have the system\n"
+           "select the interface.  @var{INTERFACEADDR} can also be an\n"
+           "interface index number, on systems supporting that.")
 #define FUNC_NAME s_scm_setsockopt
 {
   int fd;