Docs: allow for multiple return from dnsdb PTR lookup

[exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index a7625630ef099207d06216d0b6d5a202be56c168..0ac98d668ca2a76c6c92ee6abdf8f7eeb1cd55f3 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -6998,7 +6998,7 @@ IPv4, in dotted-quad form. (Exim converts IPv4-mapped IPv6 addresses to this
 notation before executing the lookup.)
 
 One option is supported, "ret=full", to request the return of the entire line
-rather than omitting the key porttion.
+rather than omitting the key portion.
 Note however that the key portion will have been de-quoted.
 
 .next
@@ -10663,16 +10663,28 @@ expansion items.
 This item inserts &"raw"& header lines. It is described with the &%header%&
 expansion item in section &<<SECTexpansionitems>>& above.
 
-.vitem "&*${run{*&<&'command'&>&*&~*&<&'args'&>&*}{*&<&'string1'&>&*}&&&
+.vitem "&*${run <&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&&
         {*&<&'string2'&>&*}}*&"
 .cindex "expansion" "running a command"
 .cindex "&%run%& expansion item"
-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
+This item runs an external command, as a subprocess.
+.new
+One option is supported after the word &'run'&, comma-separated.
+
+If the option &'preexpand'& is not used,
+the command string is split into individual arguments by spaces
+and then each argument is expanded.
+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.
+The command name may not be tainted, but the remaining arguments can be.
 
+If the option &'preexpand'& is used,
+.wen
+the command and its arguments are first expanded as one string. The result is
+split apart into individual arguments by spaces, and then the command is run
+as above.
 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
@@ -10683,6 +10695,9 @@ in a string containing quotes, because it would interfere 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.
+.new
+Neither the command nor any argument may be tainted.
+.wen
 
 The standard input for the command exists, but is empty. The standard output
 and standard error are set to the same file descriptor.
@@ -11902,6 +11917,19 @@ ${if inlisti{Needle}{fOo:NeeDLE:bAr}}
   ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
 .endd
 
+.new
+The variable &$value$& will be set for a successful match and can be
+used in the success clause of an &%if%& expansion item using the condition.
+.cindex "tainted data" "de-tainting"
+It will have the same taint status as the list; expansions such as
+.code
+${if inlist {$h_mycode:} {0 : 1 : 42} {$value}}
+.endd
+can be used for de-tainting.
+Any previous &$value$& is restored after the if.
+.wen
+
+
 .vitem &*isip&~{*&<&'string'&>&*}*&  &&&
        &*isip4&~{*&<&'string'&>&*}*& &&&
        &*isip6&~{*&<&'string'&>&*}*&
@@ -12098,6 +12126,18 @@ item can be used, as in all address lists, to cause subsequent items to
 have their local parts matched casefully. Domains are always matched
 caselessly.
 
+.new
+The variable &$value$& will be set for a successful match and can be
+used in the success clause of an &%if%& expansion item using the condition.
+.cindex "tainted data" "de-tainting"
+It will have the same taint status as the list; expansions such as
+.code
+${if match_local_part {$local_part} {alice : bill : charlotte : dave} {$value}}
+.endd
+can be used for de-tainting.
+Any previous &$value$& is restored after the if.
+.wen
+
 Note that <&'string2'&> is not itself subject to string expansion, unless
 Exim was built with the EXPAND_LISTMATCH_RHS option.
 
@@ -25468,7 +25508,8 @@ servers or different local IP addresses. For example, if you want the string
 that is used for &%helo_data%& to be obtained by a DNS lookup of the outgoing
 interface address, you could use this:
 .code
-helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\
+helo_data = ${lookup dnsdb{ptr=$sending_ip_address} \
+  {${listextract{1}{<\n $value}}} \
   {$primary_hostname}}
 .endd
 The use of &%helo_data%& applies both to sending messages and when doing
@@ -39481,7 +39522,7 @@ Include delivered recipients in queue listing.
 The following options give alternates for configuration:
 
 .vlist
-.vitem &*-C*&&~<&'config file'&>
+.vitem &*-C*&&~<&'config&~file'&>
 is used to specify an alternate &_exim.conf_& which might
 contain alternate exim configuration the queue management might be using.