Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Provider decoder man and header file mismatch #19543

Closed
Lipovlan opened this issue Oct 30, 2022 · 1 comment
Closed

Provider decoder man and header file mismatch #19543

Lipovlan opened this issue Oct 30, 2022 · 1 comment
Labels
branch: master Merge to master branch branch: 3.0 Merge to openssl-3.0 branch branch: 3.1 Merge to openssl-3.1 good first issue Bite size change that could be a good start triaged: bug The issue/pr is/fixes a bug triaged: documentation The issue/pr deals with documentation (errors)

Comments

@Lipovlan
Copy link
Contributor

I'm working with OpenSSL version 3.2.0-dev.

On line 907 in core_dispatch.h there is declared OSSL_FUNC_decoder_export_object
function. The return type is int. In documentation for provider-decoder, the return type is void *. What should the OSSL_FUNC_decoder_export_object function return?
@Lipovlan Lipovlan added the issue: documentation The issue reports errors in (or missing) documentation label Oct 30, 2022
@levitte
Copy link
Member

levitte commented Oct 30, 2022

The header file is correct.

@paulidale paulidale added branch: master Merge to master branch triaged: bug The issue/pr is/fixes a bug triaged: documentation The issue/pr deals with documentation (errors) branch: 3.0 Merge to openssl-3.0 branch branch: 3.1 Merge to openssl-3.1 good first issue Bite size change that could be a good start and removed issue: documentation The issue reports errors in (or missing) documentation labels Oct 31, 2022
bitrotlink added a commit to bitrotlink/openssl that referenced this issue Dec 26, 2022
@bitrotlink
Fix documented names and return types for some functions and signatures
03a133d 
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 return type of OSSL_FUNC_decoder_export_object_fn is wrong; the correct type is int, due to the following line in core_dispatch.h:
OSSL_CORE_MAKE_FUNC(int, decoder_export_object,

This fixes openssl#19543.

The documented claim (prior to applying this patch) 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 as function pointers in OSSL_DISPATCH arrays." Somebody else can choose suitable phrasing; this patch only fixes the names and signatures.

Trivial due to just appending "_fn" to documented names, changing a void to an int, and fixing two asterisks.

CLA: trivial
@bitrotlink bitrotlink mentioned this issue Dec 26, 2022
Closed
1 task
bitrotlink added a commit to bitrotlink/openssl that referenced this issue Mar 13, 2023
@bitrotlink
Fix documented function return types
3ce6e42 
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 openssl#19543

Per the Github conversation with levitte and t8m for pull request openssl#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
openssl-machine pushed a commit that referenced this issue Mar 16, 2023
@bitrotlink @paulidale
Fix documented function return types
d7bb9d5 
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 #19964)

(cherry picked from commit 04af51c)
openssl-machine pushed a commit that referenced this issue Mar 16, 2023
@bitrotlink @paulidale
Fix documented function return types
ebaaf35 
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 #19964)

(cherry picked from commit 04af51c)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
branch: master Merge to master branch branch: 3.0 Merge to openssl-3.0 branch branch: 3.1 Merge to openssl-3.1 good first issue Bite size change that could be a good start triaged: bug The issue/pr is/fixes a bug triaged: documentation The issue/pr deals with documentation (errors)
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Fix documented names and return types for some functions and signatures bitrotlink/openssl
3 participants
@levitte @paulidale @Lipovlan