From: Jeremy Harris Date: Sun, 24 Nov 2019 13:47:38 +0000 (+0000) Subject: Docs: smtp_printf() in the local_scan API X-Git-Tag: exim-4.93-RC5~2 X-Git-Url: https://vcs.fsf.org/?a=commitdiff_plain;h=b2d54f831659ee95d4d4cf395f568b395e262310;p=exim.git Docs: smtp_printf() in the local_scan API Broken-by: 925ac8e4f1 --- 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