Gitweb:
https://git.exim.org/exim.git/commitdiff/b2d54f831659ee95d4d4cf395f568b395e262310
Commit: b2d54f831659ee95d4d4cf395f568b395e262310
Parent: dc2d885ade485ba0d631bb7dea251e8558922648
Author: Jeremy Harris <jgh146exb@???>
AuthorDate: Sun Nov 24 13:47:38 2019 +0000
Committer: Jeremy Harris <jgh146exb@???>
CommitDate: Sun Nov 24 13:47:38 2019 +0000
Docs: smtp_printf() in the local_scan API
Broken-by: 925ac8e4f1
---
doc/doc-docbook/spec.xfpt | 23 ++++++++++++++++++++---
doc/doc-txt/ChangeLog | 3 +++
src/src/smtp_in.c | 7 ++++++-
3 files changed, 29 insertions(+), 4 deletions(-)
diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 24ed4fb..294034a 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 c5b2ca2..faf6914 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 18e04dc..f37b2f6 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
