Docs: smtp_printf() in the local_scan API

Broken-by: 925ac8e4f1

3 files changed, 29 insertions, 4 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 24ed4fb89..294034a6c 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -34313,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%&
@@ -34326,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
@@ -34343,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
diff --git a/doc/doc-txt/ChangeLog b/doc/doc-txt/ChangeLog
index c5b2ca2d8..faf6914ca 100644
--- a/doc/doc-txt/ChangeLog
+++ b/doc/doc-txt/ChangeLog
@@ -204,6 +204,9 @@ JH/44 With OpenSSL 1.1.1 (onwards) disable renegotiation for TLS1.2 and below;
       recommended to avoid a possible server-load attack.  The feature can be
       re-enabled via the openssl_options main cofiguration option.
 
+JH/45 local_scan API: documented the current smtp_printf() call. This changed
+      for version 4.90 - adding a "more data" boolean to the arguments.
+
 
 Exim version 4.92
 -----------------
diff --git a/src/src/smtp_in.c b/src/src/smtp_in.c
index 18e04dc2e..f37b2f6e0 100644
--- a/src/src/smtp_in.c
+++ b/src/src/smtp_in.c
@@ -877,6 +877,8 @@ flush for non-TLS connections. The smtp_fflush() function is available for
 checking that: for convenience, TLS output errors are remembered here so that
 they are also picked up later by smtp_fflush().
 
+This function is exposed to the local_scan API; do not change the signature.
+
 Arguments:
   format      format string
   more	      further data expected
@@ -897,7 +899,10 @@ va_end(ap);
 
 /* This is split off so that verify.c:respond_printf() can, in effect, call
 smtp_printf(), bearing in mind that in C a vararg function can't directly
-call another vararg function, only a function which accepts a va_list. */
+call another vararg function, only a function which accepts a va_list.
+
+This function is exposed to the local_scan API; do not change the signature.
+*/
 /*XXX consider passing caller-info in, for string_vformat-onward */
 
 void