From 3d95d9d6795f16eb7374a73e2ef9757a173691e5 Mon Sep 17 00:00:00 2001 From: Gerhard Rieger Date: Sat, 20 Sep 2008 21:42:50 +0200 Subject: [PATCH] improve docu and comments of generic sockets --- doc/socat.yo | 113 ++++++++++++++++++++++++++------------------------- xio-listen.c | 12 +++--- 2 files changed, 64 insertions(+), 61 deletions(-) diff --git a/doc/socat.yo b/doc/socat.yo index 741461a..d88f492 100644 --- a/doc/socat.yo +++ b/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:::))) Creates a stream socket using the first and second given socket parameters - and tt(SOCK_STREAM) (see man - socket(2)) and connects to the remote-address. The - two socket parameters have to be specified as numbers of type - link(int)(TYPE_INT). Consult your OS documentation and include files to find - the desired values. The remote-address must be the link(data)(TYPE_DATA) - representation of a sockaddr structure without the sa_family component.nl() + and tt(SOCK_STREAM) (see man socket(2)) and connects to the remote-address. + The two socket parameters have to be specified by link(int)(TYPE_INT) + numbers. Consult your OS documentation and include files to find the + appropriate values. The remote-address must be the link(data)(TYPE_DATA) + 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 - link(-s)(option_s).nl() + use options of higher level protocols when you apply socat option + 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::::::))) - Creates a datagram socket using the first three given socket parameters (see man - socket(2)) and sends outgoing data to the remote-address. The - three socket parameters have to be specified as numbers of type - link(int)(TYPE_INT). Consult your OS documentation and include files to find - the desired values. The remote-address must be the link(data)(TYPE_DATA) - representation of a sockaddr structure without the sa_family component.nl() + Creates a datagram socket using the first three given socket parameters (see + man socket(2)) and sends outgoing data to the remote-address. The three + socket parameters have to be specified by link(int)(TYPE_INT) + numbers. Consult your OS documentation and include files to find the + appropriate values. The remote-address must be the link(data)(TYPE_DATA) + 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 - link(-s)(option_s).nl() + use options of higher level protocols when you apply socat option + 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:::::))) Creates a stream socket using the first and second given socket parameters - and tt(SOCK_STREAM) (see man - socket(2)) and waits for incoming connections on local-address. The - two socket parameters have to be specified as numbers of type - link(int)(TYPE_INT). Consult your OS documentation and include files to find - the desired values. The local-address must be the link(data)(TYPE_DATA) - representation of a sockaddr structure without the sa_family component.nl() + and tt(SOCK_STREAM) (see man socket(2)) and waits for incoming connections + on local-address. The two socket parameters have to be specified by + link(int)(TYPE_INT) numbers. Consult your OS documentation and include files + to find the appropriate values. The local-address must be the + link(data)(TYPE_DATA) 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 - link(-s)(option_s).nl() + use options of higher level protocols when you apply socat option + 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::::::))) - Creates a socket using the three given socket parameters (see man - socket(2)) and binds it to . Receives arriving data. The - three parameters have to be specified as numbers of type - link(int)(TYPE_INT). Consult your OS documentation and include files to find - the desired values. The local-address must be the link(data)(TYPE_DATA) - representation of a sockaddr structure without the sa_family component.nl() + Creates a socket using the three given socket parameters (see man socket(2)) + and binds it to . Receives arriving data. The three + parameters have to be specified by link(int)(TYPE_INT) numbers. Consult your + OS documentation and include files to find the appropriate values. The + local-address must be the link(data)(TYPE_DATA) representation of a sockaddr + 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:::::::))) - Creates a socket using the three given socket parameters (see man - socket(2)) and binds it to . Receives arriving data and sends - replies 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 - include files to find the desired values. The local-address must be the - link(data)(TYPE_DATA) - representation of a sockaddr structure without the sa_family component.nl() + Creates a socket using the three given socket parameters (see man socket(2)) + and binds it to . Receives arriving data and sends replies + back to the sender. The first three parameters have to be specified as + link(int)(TYPE_INT) numbers. Consult your OS documentation and include files + to find the appropriate values. The local-address must be the + link(data)(TYPE_DATA) representation of a sockaddr structure without + 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), @@ -717,12 +718,12 @@ label(ADDRESS_SOCKET_RECVFROM)dit(bf(tt(SOCKET_RECVFROM::::::))) 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 - numbers of type link(int)(TYPE_INT). Consult your OS documentation and - include files to find the desired values. The remote-address must be the - link(data)(TYPE_DATA) representation of a sockaddr structure without the - sa_family component.nl() + socket(2)). Sends outgoing data to the given address and receives replies. + The three parameters have to be specified as link(int)(TYPE_INT) + numbers. Consult your OS documentation and include files to find the + appropriate values. The remote-address must be the link(data)(TYPE_DATA) + representation of a sockaddr structure without sa_family and (BSD) sa_len + 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=))) something like "ip4" or "ip6". label(OPTION_SETSOCKOPT_INT)dit(bf(tt(setsockopt-int=::))) Invokes tt(setsockopt()) for the socket with the given parameters. tt(level) - [link(int)(TYPE_INT)] specifies the second argument to tt(setsockopt()) - which specifies the layer, e.g. SOL_TCP (=6 on Linux) for TCP, or SOL_SOCKET - (=1 on Linux) for the socket layer. tt(optname) [link(int)(TYPE_INT)] - selects the third argument to tt(setsockopt()) option. For the actual - integer values you might have to look up the appropriate include file of - your system. The 4th tt(setsockopt()) parameter, tt(value) - [link(int)(TYPE_INT)], is passed to the function per pointer, and the length - parameter to the tt(setsockopt()) call is derived from this type. + [link(int)(TYPE_INT)] is used as second argument to tt(setsockopt()) and + specifies the layer, e.g. SOL_TCP for TCP (6 on Linux), or SOL_SOCKET for + the socket layer (1 on Linux). tt(optname) [link(int)(TYPE_INT)] is the + third argument to tt(setsockopt()) and tells which socket option is to be + set. For the actual numbers you might have to look up the appropriate include + files of your system. The 4th tt(setsockopt()) parameter, tt(value) + [link(int)(TYPE_INT)], is passed to the function per pointer, and for the + length parameter sizeof(int) is taken implicitely. label(OPTION_SETSOCKOPT_BIN)dit(bf(tt(setsockopt-bin=::))) - Like tt(setsockopt-int), but is expected in link(dalan)(TYPE_DATA) - format and specifies an arbitrary sequence of bytes. + Like tt(setsockopt-int), but must be provided in + 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=::))) Like tt(setsockopt-int), but 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() diff --git a/xio-listen.c b/xio-listen.c index 225beaf..a788c6f 100644 --- a/xio-listen.c +++ b/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 - a subprocess! + Returns 0 if a connection was accepted; with fork option, this is already in + 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) {