Fix documented function return types

The documented return type of the (incorrectly named; see below) OSSL_FUNC_decoder_export_object function signature is wrong; the correct type is int, due to the following line in core_dispatch.h:
OSSL_CORE_MAKE_FUNC(int, decoder_export_object,

Fixes #19543

Per the Github conversation with levitte and t8m for pull request #19964, the following issues are not addressed by this patch:

The macro OSSL_CORE_MAKE_FUNC in core_dispatch.h generates a function, and a corresponding function signature typedef with name ending in "_fn". The typedefed signature is unrelated to the signature of the function.
However, provider-decoder.pod describes typedefed signatures generated by the macro, but uses the names of the functions (lacking "_fn") instead of the typedefed signatures, which is a mismatch.

Also, the documented claim about OSSL_FUNC_decoder_export_object, etc that "None of these are actual functions" is contradicted by the fact that the code actually calls those functions, and calls them specifically by those names. E.g. in decoder_meth.c:
decoder->export_object = OSSL_FUNC_decoder_export_object(fns);

The functions are generated by OSSL_CORE_MAKE_FUNC.

The paragraph "None of these are actual functions"... should be replaced by something more like "These function signatures, generated by the OSSL_CORE_MAKE_FUNC macro, are for functions that are offered via function pointers in OSSL_DISPATCH arrays."

CLA: trivial

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19964)

diff --git a/doc/man7/provider-decoder.pod b/doc/man7/provider-decoder.pod
index f279955a6088cc8697ad97ce4d8fb3e74ab9221f..bde8c7038b0a7226c4661dd0ebeb32c7f18017ad 100644 (file)
--- a/doc/man7/provider-decoder.pod
+++ b/doc/man7/provider-decoder.pod
@@ -34,7 +34,7 @@ provider-decoder - The OSSL_DECODER library E<lt>-E<gt> provider functions
                               OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
 
  /* Functions to export a decoded object */
- void *OSSL_FUNC_decoder_export_object(void *ctx,
+ int OSSL_FUNC_decoder_export_object(void *ctx,
                                        const void *objref, size_t objref_sz,
                                        OSSL_CALLBACK *export_cb,
                                        void *export_cbarg);
@@ -83,7 +83,7 @@ For example, the "function" OSSL_FUNC_decoder_decode() has these:
                                    int selection,
                                    OSSL_CALLBACK *data_cb, void *data_cbarg,
                                    OSSL_PASSPHRASE_CALLBACK *cb, void *cbarg);
- static ossl_inline OSSL_FUNC_decoder_decode_fn
+ static ossl_inline OSSL_FUNC_decoder_decode_fn*
      OSSL_FUNC_decoder_decode(const OSSL_DISPATCH *opf);
 
 L<OSSL_DISPATCH(3)> arrays are indexed by numbers that are provided as