X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/5428a9463ae1080029a84a1b33e4a8a6915c5f28..6e62c454f618d77c69bea88c01e71765a1320dce:/doc/doc-docbook/spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 5f1c25f41..1ba0a10dd 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9181,6 +9181,44 @@ of <&'string2'&>, whichever is the shorter. Do not confuse &%length%& with
 &%strlen%&, which gives the length of a string.
 
 
+.vitem "&*${listextract{*&<&'number'&>&*}&&&
+        {*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&"
+.cindex "expansion" "extracting list elements by number"
+.cindex "&%listextract%&" "extract list elements by number"
+.cindex "list" "extracting elements by number"
+The <&'number'&> argument must consist entirely of decimal digits,
+apart from an optional leading minus,
+and leading and trailing white space (which is ignored).
+
+After expansion, <&'string1'&> is interpreted as a list, colon-separated by
+default, but the separator can be changed in the usual way.
+
+The first field of the list is numbered one.
+If the number is negative, the fields are
+counted from the end of the list, with the rightmost one numbered -1.
+The numbered element of the list is extracted and placed in &$value$&,
+then <&'string2'&> is expanded as the result.
+
+If the modulus of the
+number is zero or greater than the number of fields in the string,
+the result is the expansion of <&'string3'&>.
+
+For example:
+.code
+${listextract{2}{x:42:99}}
+.endd
+yields &"42"&, and
+.code
+${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}}
+.endd
+yields &"result: 99"&.
+
+If {<&'string3'&>} is omitted, an empty string is used for string3.
+If {<&'string2'&>} is also omitted, the value that was
+extracted is used.
+You can use &`fail`& instead of {<&'string3'&>} as in a string extract.
+
+
 .vitem "&*${lookup{*&<&'key'&>&*}&~*&<&'search&~type'&>&*&~&&&
         {*&<&'file'&>&*}&~{*&<&'string1'&>&*}&~{*&<&'string2'&>&*}}*&"
 This is the first of one of two different types of lookup item, which are both
@@ -13652,6 +13690,9 @@ a very large time at the end of the list. For example:
 .code
 delay_warning = 2h:12h:99d
 .endd
+Note that the option is only evaluated at the time a delivery attempt fails,
+which depends on retry and queue-runner configuration.
+Typically retries will be configured more frequently than warning messages.
 
 .option delay_warning_condition main string&!! "see below"
 .vindex "&$domain$&"
@@ -27251,7 +27292,12 @@ It is usable in the RCPT ACL and valid only for single-recipient mails forwarded
 from one SMTP connection to another.  If a recipient-verify callout connection is
 requested in the same ACL it is held open and used for the data, otherwise one is made
 after the ACL completes.
-Note that routers are used in verify mode.
+
+Note that routers are used in verify mode.  Note also that headers cannot be
+modified by any of the post-data ACLs (DATA, MIME and DKIM).
+Cutthrough delivery is not supported via transport-filters or when DKIM signing
+of outgoing messages is done, because it sends data to the ultimate destination
+before the entire message has been received from the source.
 
 Should the ultimate destination system positively accept or reject the mail,
 a corresponding indication is given to the source system and nothing is queued.
@@ -27505,12 +27551,15 @@ warn dnslists = sbl.spamhaus.org : \
      add_header = X-blacklisted-at: $dnslist_domain
 .endd
 The &%add_header%& modifier is permitted in the MAIL, RCPT, PREDATA, DATA,
-MIME, and non-SMTP ACLs (in other words, those that are concerned with
+MIME, DKIM, and non-SMTP ACLs (in other words, those that are concerned with
 receiving a message). The message must ultimately be accepted for
 &%add_header%& to have any significant effect. You can use &%add_header%& with
 any ACL verb, including &%deny%& (though this is potentially useful only in a
 RCPT ACL).
 
+Headers will not be added to the message if the modifier is used in
+DATA, MIME or DKIM ACLs for messages delivered by cutthrough routing.
+
 Leading and trailing newlines are removed from
 the data for the &%add_header%& modifier; if it then
 contains one or more newlines that
@@ -27604,12 +27653,15 @@ warn   message        = Remove internal headers
        remove_header  = x-route-mail1 : x-route-mail2
 .endd
 The &%remove_header%& modifier is permitted in the MAIL, RCPT, PREDATA, DATA,
-MIME, and non-SMTP ACLs (in other words, those that are concerned with
+MIME, DKIM, and non-SMTP ACLs (in other words, those that are concerned with
 receiving a message). The message must ultimately be accepted for
 &%remove_header%& to have any significant effect. You can use &%remove_header%&
 with any ACL verb, including &%deny%&, though this is really not useful for
 any verb that doesn't result in a delivered message.
 
+Headers will not be removed to the message if the modifier is used in
+DATA, MIME or DKIM ACLs for messages delivered by cutthrough routing.
+
 More than one header can be removed at the same time by using a colon separated
 list of header names. The header matching is case insensitive. Wildcards are
 not permitted, nor is list expansion performed, so you cannot use hostlists to
@@ -36297,7 +36349,9 @@ disabled by setting DISABLE_DKIM=yes in Local/Makefile.
 Exim's DKIM implementation allows to
 .olist
 Sign outgoing messages: This function is implemented in the SMTP transport.
-It can co-exist with all other Exim features, including transport filters.
+It can co-exist with all other Exim features
+(including transport filters)
+except cutthrough delivery.
 .next
 Verify signatures in incoming messages: This is implemented by an additional
 ACL (acl_smtp_dkim), which can be called several times per message, with
@@ -36388,6 +36442,10 @@ used.
 Verification of DKIM signatures in incoming email is implemented via the
 &%acl_smtp_dkim%& ACL. By default, this ACL is called once for each
 syntactically(!) correct signature in the incoming message.
+A missing ACL definition defaults to accept.
+If any ACL call does not acccept, the message is not accepted.
+If a cutthrough delivery was in progress for the message it is
+summarily dropped (having wasted the transmission effort).
 
 To evaluate the signature in the ACL a large number of expansion variables
 containing the signature status and its details are set up during the