Docs: smtp_printf() in the local_scan API
authorJeremy Harris <jgh146exb@wizmail.org>
Sun, 24 Nov 2019 13:47:38 +0000 (13:47 +0000)
committerJeremy Harris <jgh146exb@wizmail.org>
Sun, 24 Nov 2019 13:47:38 +0000 (13:47 +0000)
Broken-by: 925ac8e4f1
doc/doc-docbook/spec.xfpt
doc/doc-txt/ChangeLog
src/src/smtp_in.c

index 24ed4fb..294034a 100644 (file)
@@ -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
index c5b2ca2..faf6914 100644 (file)
@@ -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
 -----------------
index 18e04dc..f37b2f6 100644 (file)
@@ -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