From: Guilhem Moulin <guilhem@fripost.org>
Date: Mon, 27 May 2019 16:40:49 +0000 (+0200)
Subject: Manpages: clarify that the tunnel command is run following Perl's `exec` semantics.
X-Git-Url: https://git.g-eek.se/?a=commitdiff_plain;h=7c4d78faf324dab6428dc414ac84ecda1a18e685;p=interimap.git

Manpages: clarify that the tunnel command is run following Perl's `exec` semantics.

It is passed to `/bin/sh -c` when it contains shell metacharacters; and
split into words and passed to execvp(3) otherwise.

        https://perldoc.perl.org/functions/exec.html

(Since c8fb54897f046a5a3fb4c1d45dc21fd8bcd882e3 the value no longer
needs to stard with a forward slash.)
---

diff --git a/Changelog b/Changelog
index a13801a..b9d08a8 100644
--- a/Changelog
+++ b/Changelog
@@ -29,6 +29,10 @@ interimap (0.5) upstream;
    BLOB.
  + interimap: use the 'user_version' SQLite PRAGMA for database schema
    version.
+ + interimap, pullimap: in the manpage, clarify that the tunnel command
+   is run following Perl's `exec` semantics: it is passed to `/bin/sh -c`
+   when it contains shell metacharacters; and split into words and passed
+   to execvp(3) otherwise.
  - libinterimap: bugfix: hierarchy delimiters in LIST responses were
    returned as an escaped quoted special, like "\\", not as a single
    character (backslash in this case).
diff --git a/interimap.md b/interimap.md
index 50c1832..31d7c3f 100644
--- a/interimap.md
+++ b/interimap.md
@@ -314,7 +314,9 @@ Valid options are:
 
 :   Command to use for `type=tunnel`.  Must speak the [IMAP4rev1
     protocol][RFC 3501] on its standard output, and understand it on its
-    standard input.
+    standard input.  The value is passed to `` `/bin/sh -c` `` if it
+    contains shell metacharacters; otherwise it is split into words and
+    the list is passed to `execvp`(3).
 
 *STARTTLS*
 
diff --git a/pullimap.md b/pullimap.md
index a367dd1..72418aa 100644
--- a/pullimap.md
+++ b/pullimap.md
@@ -131,8 +131,9 @@ Valid options are:
 :   One of `imap`, `imaps` or `tunnel`.
     `type=imap` and `type=imaps` are respectively used for IMAP and IMAP
     over SSL/TLS connections over a INET socket.
-    `type=tunnel` causes `pullimap` to open a pipe to a *command*
-    instead of a raw socket.
+    `type=tunnel` causes `pullimap` to create an unnamed pair of
+    connected sockets for interprocess communication with a *command*
+    instead of a opening a network socket.
     (Default: `imaps`.)
 
 *host*
@@ -160,7 +161,9 @@ Valid options are:
 
 :   Command to use for `type=tunnel`.  Must speak the [IMAP4rev1
     protocol][RFC 3501] on its standard output, and understand it on its
-    standard input.
+    standard input.  The value is passed to `` `/bin/sh -c` `` if it
+    contains shell metacharacters; otherwise it is split into words and
+    the list is passed to `execvp`(3).
 
 *STARTTLS*