STORE: Add info on the expected post_process callback behavior

Reviewed-by: Ben Kaduk <kaduk@mit.edu>
(Merged from https://github.com/openssl/openssl/pull/3856)

diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod
index 0bc6d5ccfd87ceb3a92501300f42b85e208c0c1e..3a05a880778c38761595c1d506662dfe72ba60ee 100644 (file)
--- a/doc/man3/OSSL_STORE_open.pod
+++ b/doc/man3/OSSL_STORE_open.pod
@@ -55,6 +55,10 @@ The given B<ui_method> and B<ui_data_data> will be reused by all
 functions that use B<OSSL_STORE_CTX> when interaction is needed.
 The given B<post_process> and B<post_process_data> will be reused by
 OSSL_STORE_load() to manipulate or drop the value to be returned.
 functions that use B<OSSL_STORE_CTX> when interaction is needed.
 The given B<post_process> and B<post_process_data> will be reused by
 OSSL_STORE_load() to manipulate or drop the value to be returned.

+The B<post_process> function drops values by returning B<NULL>, which
+will cause OSSL_STORE_load() to start its process over with loading
+the next object, until B<post_process> returns something other than
+B<NULL>, or the end of data is reached as indicated by OSSL_STORE_eof().

 
 OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> and
 more arguments not specified here.
 
 OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> and
 more arguments not specified here.