Docs: smtp_printf() in the local_scan API

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index bca6689b69e9be18ce516344723c7eec285c2133..294034a6c5f215c16de5d9549ea8f54b7fd1125d 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -9485,9 +9485,15 @@ set in &_Local/Makefile_&. Once loaded, Exim remembers the dynamically loaded
 object so that it doesn't reload the same object file in the same Exim process
 (but of course Exim does start new processes frequently).
 
-There may be from zero to eight arguments to the function. When compiling
-a local function that is to be called in this way, &_local_scan.h_& should be
-included. The Exim variables and functions that are defined by that API
+There may be from zero to eight arguments to the function.
+
+.new
+When compiling
+a local function that is to be called in this way,
+first &_DLFUNC_IMPL_& should be defined,
+and second &_local_scan.h_& should be included.
+.wen
+The Exim variables and functions that are defined by that API
 are also available for dynamically loaded functions. The function itself
 must have the following type:
 .code
@@ -13516,6 +13522,19 @@ the transport.
 .vindex &$tls_out_tlsa_usage$&
 Bitfield of TLSA record types found.  See section &<<SECDANE>>&.
 
+.new
+.vitem &$tls_in_ver$&
+.vindex "&$tls_in_ver$&"
+When a message is received from a remote host over an encrypted SMTP connection
+this variable is set to the protocol version, eg &'TLS1.2'&.
+
+.vitem &$tls_out_ver$&
+.vindex "&$tls_out_ver$&"
+When a message is being delivered to a remote host over an encrypted SMTP connection
+this variable is set to the protocol version.
+.wen
+
+
 .vitem &$tod_bsdinbox$&
 .vindex "&$tod_bsdinbox$&"
 The time of day and the date, in the format required for BSD-style mailbox
@@ -16283,7 +16302,7 @@ harm. This option overrides the &%pipe_as_creator%& option of the &(pipe)&
 transport driver.
 
 
-.option openssl_options main "string list" "+no_sslv2 +no_sslv3 +single_dh_use +no_ticket"
+.option openssl_options main "string list" "+no_sslv2 +no_sslv3 +single_dh_use +no_ticket +no_renegotiation"
 .cindex "OpenSSL "compatibility options"
 This option allows an administrator to adjust the SSL options applied
 by OpenSSL to connections.  It is given as a space-separated list of items,
@@ -16750,6 +16769,7 @@ received_header_text = Received: \
         ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\
   by $primary_hostname \
   ${if def:received_protocol {with $received_protocol }}\
+  ${if def:tls_ver           { ($tls_ver)}}\
   ${if def:tls_in_cipher_std { tls $tls_in_cipher_std\n\t}}\
   (Exim $version_number)\n\t\
   ${if def:sender_address \
@@ -34293,8 +34313,10 @@ with translation.
 This function is used in conjunction with &'smtp_printf()'&, as described
 below.
 
-.vitem &*void&~smtp_printf(char&~*,&~...)*&
-The arguments of this function are like &[printf()]&; it writes to the SMTP
+.new
+.vitem &*void&~smtp_printf(char&~*,BOOL,&~...)*&
+The arguments of this function are almost like &[printf()]&; it writes to the SMTP
+.wen
 output stream. You should use this function only when there is an SMTP output
 stream, that is, when the incoming message is being received via interactive
 SMTP. This is the case when &%smtp_input%& is TRUE and &%smtp_batched_input%&
@@ -34306,6 +34328,17 @@ is involved.
 If an SMTP TLS connection is established, &'smtp_printf()'& uses the TLS
 output function, so it can be used for all forms of SMTP connection.
 
+.new
+The second argument is used to request that the data be buffered
+(when TRUE) or flushed (along with any previously buffered, when FALSE).
+This is advisory only, but likely to save on system-calls and packets
+sent when a sequence of calls to the function are made.
+
+The argument was added in Exim version 4.90 - changing the API.
+Nobody noticed until 4.93 was imminent.
+A decision on the way forward has not yet been made.
+.wen
+
 Strings that are written by &'smtp_printf()'& from within &[local_scan()]&
 must start with an appropriate response code: 550 if you are going to return
 LOCAL_SCAN_REJECT, 451 if you are going to return
@@ -34323,7 +34356,11 @@ the data returned via the &%return_text%& argument. The added value of using
 multiple output lines.
 
 The &'smtp_printf()'& function does not return any error indication, because it
-does not automatically flush pending output, and therefore does not test
+does not
+.new
+guarantee a flush of
+.wen
+pending output, and therefore does not test
 the state of the stream. (In the main code of Exim, flushing and error
 detection is done when Exim is ready for the next SMTP input command.) If
 you want to flush the output and check for an error (for example, the