Enhance documentation of ${run command parsing.
authorTodd Lyons <tlyons@exim.org>
Thu, 3 Jul 2014 15:32:48 +0000 (08:32 -0700)
committerTodd Lyons <tlyons@exim.org>
Thu, 3 Jul 2014 15:32:48 +0000 (08:32 -0700)
doc/doc-docbook/spec.xfpt
doc/doc-txt/ChangeLog

index a1422b0..795d3a1 100644 (file)
@@ -9597,11 +9597,24 @@ expansion item above.
         {*&<&'string2'&>&*}}*&"
 .cindex "expansion" "running a command"
 .cindex "&%run%& expansion item"
-The command and its arguments are first expanded separately, and then the
-command is run in a separate process, but under the same uid and gid. As in
-other command executions from Exim, a shell is not used by default. If you want
+.new
+The command and its arguments are first expanded as one string. The string is
+split apart into individual arguments by spaces, and then the command is run
+in a separate process, but under the same uid and gid.  As in other command
+executions from Exim, a shell is not used by default. If the command requires
 a shell, you must explicitly code it.
 
+Since the arguments are split by spaces, when there is a variable expansion
+which has an empty result, it will cause the situation that the argument will
+simply be omitted when the program is actually executed by Exim. If the
+script/program requires a specific number of arguments and the expanded
+variable could possibly result in this empty expansion, the variable must be
+quoted. This is more difficult if the expanded variable itself could result
+in a string containing quotes, because it would with the quotes around the
+command arguments. A possible guard against this is to wrap the variable in
+the &%sg%& operator to change any quote marks to some other character.
+.wen
+
 The standard input for the command exists, but is empty. The standard output
 and standard error are set to the same file descriptor.
 .cindex "return code" "from &%run%& expansion"
index 40a2443..83a0663 100644 (file)
@@ -138,6 +138,10 @@ TF/03 Fix udpsend. The ip_connectedsocket() function's socket type
 TL/13 Bug 1495: Exiqgrep check if -C config file specified on cli exists
       and is readable.  Patch from Andrew Colin Kissa.
 
+TL/14 Enhance documentation of ${run expansion and how it parses the
+      commandline after expansion, particularly in the case when an
+      unquoted variable expansion results in an empty value.
+
 
 Exim version 4.82
 -----------------