improve docu and comments of generic sockets

doc/socat.yo

@@ -10,7 +10,7 @@ def(Filan)(0)(bf(Filan))
 def(procan)(0)(bf(procan))
 def(Procan)(0)(bf(Procan))
 
-manpage(socat)(1)(Feb 2008)(socat)()
+manpage(socat)(1)(Sep 2008)(socat)()
 
 whenhtml(
 label(CONTENTS)
@@ -601,15 +601,15 @@ label(ADDRESS_READLINE)dit(bf(tt(READLINE)))
    link(STDIO)(ADDRESS_STDIO)
 label(ADDRESS_SOCKET_CONNECT)dit(bf(tt(SOCKET-CONNECT:<domain>:<protocol>:<remote-address>)))
    Creates a stream socket using the first and second given socket parameters
-   and tt(SOCK_STREAM) (see man
+   and tt(SOCK_STREAM) (see man socket(2)) and connects to the remote-address.
-   socket(2)) and connects to the remote-address. The
+   The two socket parameters have to be specified by link(int)(TYPE_INT)
-   two socket parameters have to be specified as numbers of type 
+   numbers. Consult your OS documentation and include files to find the
-   link(int)(TYPE_INT). Consult your OS documentation and include files to find
+   appropriate values. The remote-address must be the link(data)(TYPE_DATA)
-   the desired values. The remote-address must be the link(data)(TYPE_DATA)
+   representation of a sockaddr structure without sa_family and (BSD) sa_len
-   representation of a sockaddr structure without the sa_family component.nl()
+   components.nl()
    Please note that you can - beyond the options of the specified groups - also
-   apply options of higher level protocols when you use socat option
+   use options of higher level protocols when you apply socat option
-   link(-s)(option_s).nl()
+   link(-g)(option_g).nl()
    Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY)nl()
    Useful options:
    link(bind)(OPTION_BIND),
@@ -624,15 +624,16 @@ label(ADDRESS_SOCKET_CONNECT)dit(bf(tt(SOCKET-CONNECT:<domain>:<protocol>:<remot
    link(SOCKET-LISTEN)(ADDRESS_SOCKET_LISTEN),
    link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO)
 label(ADDRESS_SOCKET_DATAGRAM)dit(bf(tt(SOCKET-DATAGRAM:<domain>:<type>:<protocol>:<remote-address>)))
-   Creates a datagram socket using the first three given socket parameters (see man
+   Creates a datagram socket using the first three given socket parameters (see
-   socket(2)) and sends outgoing data to the remote-address. The
+   man socket(2)) and sends outgoing data to the remote-address. The three
-   three socket parameters have to be specified as numbers of type 
+   socket parameters have to be specified by link(int)(TYPE_INT)
-   link(int)(TYPE_INT). Consult your OS documentation and include files to find
+   numbers. Consult your OS documentation and include files to find the
-   the desired values. The remote-address must be the link(data)(TYPE_DATA)
+   appropriate values. The remote-address must be the link(data)(TYPE_DATA)
-   representation of a sockaddr structure without the sa_family component.nl()
+   representation of a sockaddr structure without sa_family and (BSD) sa_len
+   components.nl()
    Please note that you can - beyond the options of the specified groups - also
-   apply options of higher level protocols when you use socat option
+   use options of higher level protocols when you apply socat option
-   link(-s)(option_s).nl()
+   link(-g)(option_g).nl()
    Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(RANGE)(GROUP_RANGE)
    Useful options:
    link(bind)(OPTION_BIND),
@@ -649,15 +650,15 @@ label(ADDRESS_SOCKET_DATAGRAM)dit(bf(tt(SOCKET-DATAGRAM:<domain>:<type>:<protoco
    link(SOCKET-RECVFROM)(ADDRESS_SOCKET_RECVFROM)
 label(ADDRESS_SOCKET_LISTEN)dit(bf(tt(SOCKET-LISTEN:<domain>:<protocol>:<local-address>)))
    Creates a stream socket using the first and second given socket parameters
-   and tt(SOCK_STREAM) (see man
+   and tt(SOCK_STREAM) (see man socket(2)) and waits for incoming connections
-   socket(2)) and waits for incoming connections on local-address. The
+   on local-address. The two socket parameters have to be specified by
-   two socket parameters have to be specified as numbers of type 
+   link(int)(TYPE_INT) numbers. Consult your OS documentation and include files
-   link(int)(TYPE_INT). Consult your OS documentation and include files to find
+   to find the appropriate values. The local-address must be the
-   the desired values. The local-address must be the link(data)(TYPE_DATA)
+   link(data)(TYPE_DATA) representation of a sockaddr structure without
-   representation of a sockaddr structure without the sa_family component.nl()
+   sa_family and (BSD) sa_len components.nl()
    Please note that you can - beyond the options of the specified groups - also
-   apply options of higher level protocols when you use socat option
+   use options of higher level protocols when you apply socat option
-   link(-s)(option_s).nl()
+   link(-g)(option_g).nl()
    Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(LISTEN)(GROUP_LISTEN),link(RANGE)(GROUP_RANGE),link(CHILD)(GROUP_CHILD),link(RETRY)(GROUP_RETRY)nl()
    Useful options:
    link(setsockopt-int)(OPTION_SETSOCKOPT_INT),
@@ -672,12 +673,12 @@ label(ADDRESS_SOCKET_LISTEN)dit(bf(tt(SOCKET-LISTEN:<domain>:<protocol>:<local-a
    link(SOCKET-SENDTO)(ADDRESS_SOCKET_RECVFROM),
    link(SOCKET-SENDTO)(ADDRESS_SOCKET_RECV)
 label(ADDRESS_SOCKET_RECV)dit(bf(tt(SOCKET_RECV:<domain>:<type>:<protocol>:<local-address>)))
-   Creates a socket using the three given socket parameters (see man
+   Creates a socket using the three given socket parameters (see man socket(2))
-   socket(2)) and binds it to <local-address>. Receives arriving data. The
+   and binds it to <local-address>. Receives arriving data. The three
-   three parameters have to be specified as numbers of type 
+   parameters have to be specified by link(int)(TYPE_INT) numbers. Consult your
-   link(int)(TYPE_INT). Consult your OS documentation and include files to find
+   OS documentation and include files to find the appropriate values. The
-   the desired values. The local-address must be the link(data)(TYPE_DATA)
+   local-address must be the link(data)(TYPE_DATA) representation of a sockaddr
-   representation of a sockaddr structure without the sa_family component.nl()
+   structure without sa_family and (BSD) sa_len components.nl()
    Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(RANGE)(GROUP_RANGE)
    Useful options:
    link(range)(OPTION_RANGE),
@@ -693,13 +694,13 @@ label(ADDRESS_SOCKET_RECV)dit(bf(tt(SOCKET_RECV:<domain>:<type>:<protocol>:<loca
    link(SOCKET-SENDTO)(ADDRESS_SOCKET_SENDTO),
    link(SOCKET-RECVFROM)(ADDRESS_SOCKET_RECVFROM)
 label(ADDRESS_SOCKET_RECVFROM)dit(bf(tt(SOCKET_RECVFROM:<domain>:<type>:<protocol>:<local-address>)))
-   Creates a socket using the three given socket parameters (see man
+   Creates a socket using the three given socket parameters (see man socket(2))
-   socket(2)) and binds it to <local-address>. Receives arriving data and sends
+   and binds it to <local-address>. Receives arriving data and sends replies
-   replies back to the sender. The first three parameters have to be specified as
+   back to the sender. The first three parameters have to be specified as
-   numbers of type link(int)(TYPE_INT). Consult your OS documentation and
+   link(int)(TYPE_INT) numbers. Consult your OS documentation and include files
-   include files to find the desired values. The local-address must be the
+   to find the appropriate values. The local-address must be the
-   link(data)(TYPE_DATA)
+   link(data)(TYPE_DATA) representation of a sockaddr structure without
-   representation of a sockaddr structure without the sa_family component.nl()
+   sa_family and (BSD) sa_len components.nl()
    Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE)
    Useful options:
    link(fork)(OPTION_FORK),
@@ -718,11 +719,11 @@ label(ADDRESS_SOCKET_RECVFROM)dit(bf(tt(SOCKET_RECVFROM:<domain>:<type>:<protoco
 label(ADDRESS_SOCKET_SENDTO)dit(bf(tt(SOCKET_SENDTO:<domain>:<type>:<protocol>:<remote-address>)))
    Creates a socket using the three given socket parameters (see man
    socket(2)). Sends outgoing data to the given address and receives replies.
-   The three parameters have to be specified as
+   The three parameters have to be specified as link(int)(TYPE_INT)
-   numbers of type link(int)(TYPE_INT). Consult your OS documentation and
+   numbers. Consult your OS documentation and include files to find the
-   include files to find the desired values. The remote-address must be the
+   appropriate values. The remote-address must be the link(data)(TYPE_DATA)
-   link(data)(TYPE_DATA) representation of a sockaddr structure without the
+   representation of a sockaddr structure without sa_family and (BSD) sa_len
-   sa_family component.nl()
+   components.nl()
    Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET)
    Useful options:
    link(bind)(OPTION_BIND),
@@ -1793,20 +1794,22 @@ label(OPTION_PROTOCOL_FAMILY)dit(bf(tt(pf=<string>)))
    something like "ip4" or "ip6".
 label(OPTION_SETSOCKOPT_INT)dit(bf(tt(setsockopt-int=<level>:<optname>:<optval>)))
    Invokes tt(setsockopt()) for the socket with the given parameters. tt(level)
-   [link(int)(TYPE_INT)] specifies the second argument to tt(setsockopt())
+   [link(int)(TYPE_INT)] is used as second argument to tt(setsockopt()) and
-   which specifies the layer, e.g. SOL_TCP (=6 on Linux) for TCP, or SOL_SOCKET
+   specifies the layer, e.g. SOL_TCP for TCP (6 on Linux), or SOL_SOCKET for
-   (=1 on Linux) for the socket layer. tt(optname) [link(int)(TYPE_INT)]
+   the socket layer (1 on Linux). tt(optname) [link(int)(TYPE_INT)] is the
-   selects the third argument to tt(setsockopt()) option. For the actual
+   third argument to tt(setsockopt()) and tells which socket option is to be
-   integer values you might have to look up the appropriate include file of
+   set. For the actual numbers you might have to look up the appropriate include
-   your system. The 4th tt(setsockopt()) parameter, tt(value)
+   files of your system. The 4th tt(setsockopt()) parameter, tt(value)
-   [link(int)(TYPE_INT)], is passed to the function per pointer, and the length
+   [link(int)(TYPE_INT)], is passed to the function per pointer, and for the
-   parameter to the tt(setsockopt()) call is derived from this type.
+   length parameter sizeof(int) is taken implicitely.
 label(OPTION_SETSOCKOPT_BIN)dit(bf(tt(setsockopt-bin=<level>:<optname>:<optval>)))
-   Like tt(setsockopt-int), but <optval> is expected in link(dalan)(TYPE_DATA)
+   Like tt(setsockopt-int), but <optval> must be provided in
-   format and specifies an arbitrary sequence of bytes.
+   link(dalan)(TYPE_DATA) format and specifies an arbitrary sequence of bytes;
+   the length parameter is automatically derived from the data.
 label(OPTION_SETSOCKOPT_STRING)dit(bf(tt(setsockopt-string=<level>:<optname>:<optval>)))
    Like tt(setsockopt-int), but <optval> must be a link(string)(TYPE_STRING).
-   This string is passed to the function with trailing null character.
+   This string is passed to the function with trailing null character, and the
+   length parameter is automatically derived from the data.
 enddit()
 
 startdit()enddit()nl()

xio-listen.c

@@ -81,18 +81,18 @@ int
 }
 
 
-/* waits for incoming connection, checks its source address and port. Depending
+/* Waits for incoming connection, checks its source address and port. Depending
    on fork option, it may fork a subprocess.
    pf specifies the syntax expected for range option. In the case of generic
-   socket it is 0 (expcting raw binary data), and the real pf can be obtained
+   socket it is 0 (expecting raw binary data), and the real pf can be obtained
    from us->af_family; for other socket types pf == us->af_family
-   Returns 0 if a connection was accepted; with fork option, this is always in
+   Returns 0 if a connection was accepted; with fork option, this is already in
-   a subprocess!
+   the subprocess!
    Other return values indicate a problem; this can happen in the master
-   process or in a subprocess.
+   process or in the subprocess.
    This function does not retry. If you need retries, handle this is a
    loop in the calling function.
-   after fork, we set the forever/retry of the child process to 0
+   After fork, we set the forever/retry of the child process to 0
  */
 int _xioopen_listen(struct single *xfd, int xioflags, struct sockaddr *us, socklen_t uslen,
 		 struct opt *opts, int pf, int socktype, int proto, int level) {