From c4fe75fd62ad8b53e98472874c07182f74832ecb Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sat, 10 Sep 2016 15:01:14 +0000
Subject:  Add options to s6-tcpserver4-socketbinder and
 s6-tcpserver6-socketbinder to create UDP sockets; also to not listen().
 (Suggested by Daniel Kahn Gillmor.)

---
 doc/s6-tcpserver4-socketbinder.html | 15 ++++++++++++---
 doc/s6-tcpserver6-socketbinder.html | 15 ++++++++++++---
 2 files changed, 24 insertions(+), 6 deletions(-)

(limited to 'doc')

diff --git a/doc/s6-tcpserver4-socketbinder.html b/doc/s6-tcpserver4-socketbinder.html
index 4cb75ee..d8c2ba9 100644
--- a/doc/s6-tcpserver4-socketbinder.html
+++ b/doc/s6-tcpserver4-socketbinder.html
@@ -26,7 +26,7 @@ socket to an IPv4 address and port, then executes a program.
 <h2> Interface </h2>
 
 <pre>
-     s6-tcpserver4-socketbinder [ -d | -D ] [ -b <em>backlog</em> ] <em>ip</em> <em>port</em> <em>prog...</em>
+     s6-tcpserver4-socketbinder [ -d | -D ] [ -b <em>backlog</em> ] [ -M | -m ] <em>ip</em> <em>port</em> <em>prog...</em>
 </pre>
 
 <ul>
@@ -47,13 +47,22 @@ even if it has been used not long ago - this is the SO_REUSEADDR flag to
 and is generally used with server programs. This is the default. </li>
  <li> <tt>-D</tt>&nbsp;: disallow instant rebinding to the same path. </li>
  <li> <tt>-b&nbsp;<em>backlog</em></tt>&nbsp;: set a maximum of
-<em>backlog</em> backlog connections on the socket. Extra
-connection attempts will rejected by the kernel. </li>
+<em>backlog</em> backlog connections on the socket - extra
+connection attempts will rejected by the kernel. The default is SOMAXCONN,
+i.e. the maximum number allowed by the system. If <em>backlog</em>
+is 0, then the socket will be created, but it <strong>will not be
+listening</em>. </li>
+ <li> <tt>-M</tt>&nbsp;: create a TCP socket. This is the default. </li>
+ <li> <tt>-m</tt>&nbsp;: create a UDP socket. Note
+that by default UDP sockets are not connection-mode, and <tt>listen()</tt>
+will fail - so you should always give the <tt>-b0</tt> option to
+s6-tcpserver4-socketbinder along with <tt>-m</tt>. </li>
 </ul>
 
 <h2> Notes </h2>
 
 <ul>
+ <li> The socket is provided <strong>non-blocking</strong>. </li>
  <li> s6-tcpserver4-socketbinder is part of a set of basic blocks used to
 build a flexible TCP/IPv4 super-server. It normally should be given a
 command line crafted to make it execute into
diff --git a/doc/s6-tcpserver6-socketbinder.html b/doc/s6-tcpserver6-socketbinder.html
index ea2bc24..d497342 100644
--- a/doc/s6-tcpserver6-socketbinder.html
+++ b/doc/s6-tcpserver6-socketbinder.html
@@ -26,7 +26,7 @@ socket to an IPv6 address and port, then executes a program.
 <h2> Interface </h2>
 
 <pre>
-     s6-tcpserver6-socketbinder [ -d | -D ] [ -b <em>backlog</em> ] <em>ip</em> <em>port</em> <em>prog...</em>
+     s6-tcpserver6-socketbinder [ -d | -D ] [ -b <em>backlog</em> ] [ -M | -m ] <em>ip</em> <em>port</em> <em>prog...</em>
 </pre>
 
 <ul>
@@ -47,13 +47,22 @@ even if it has been used not long ago - this is the SO_REUSEADDR flag to
 and is generally used with server programs. This is the default. </li>
  <li> <tt>-D</tt>&nbsp;: disallow instant rebinding to the same path. </li>
  <li> <tt>-b&nbsp;<em>backlog</em></tt>&nbsp;: set a maximum of
-<em>backlog</em> backlog connections on the socket. Extra
-connection attempts will rejected by the kernel. </li>
+<em>backlog</em> backlog connections on the socket - extra
+connection attempts will rejected by the kernel. The default is SOMAXCONN,
+i.e. the maximum number allowed by the system. If <em>backlog</em>
+is 0, then the socket will be created, but it <strong>will not be
+listening</em>. </li>
+ <li> <tt>-M</tt>&nbsp;: create a TCP socket. This is the default. </li>
+ <li> <tt>-m</tt>&nbsp;: create a UDP socket. Note
+that by default UDP sockets are not connection-mode, and <tt>listen()</tt>
+will fail - so you should always give the <tt>-b0</tt> option to
+s6-tcpserver6-socketbinder along with <tt>-m</tt>. </li>
 </ul>
 
 <h2> Notes </h2>
 
 <ul>
+ <li> The socket is provided <strong>non-blocking</strong>. </li>
  <li> s6-tcpserver6-socketbinder is part of a set of basic blocks used to
 build a flexible TCP/IPv6 super-server. It normally should be given a
 command line crafted to make it execute into
-- 
cgit v1.2.3