docs: update OSSL_PARAM_int documentation

This change adds an example to allow compilation without warnings using
compiler options like `-Wincompatible-pointer-types-discards-qualifiers`

Code for the example was inspired by libarchive's https://github.com/libarchive/libarchive/pull/1869/commits/9e3a7e4b6c77e8aa19a69430f48917dbc15b319d

Fixes #20956

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

(cherry picked from commit b83b67fe59511de951db1987fb2ab9e028e2da32)

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index 22fd0f0d7dd7f35a2c754405b2c893a4ebddf461..405a0dd928cdf5231419c5329d444d887b592abc 100644 (file)
--- a/doc/man3/OSSL_PARAM.pod
+++ b/doc/man3/OSSL_PARAM.pod
@@ -356,7 +356,7 @@ could fill in the parameters like this:
 
 =head1 SEE ALSO
 
-L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)>
+L<openssl-core.h(7)>, L<OSSL_PARAM_get_int(3)>, L<OSSL_PARAM_dup(3)>, L<OSSL_PARAM_construct_utf8_string(3)>
 
 =head1 HISTORY
 

diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod
index dae0de083a62de0f5cc0b5484b617d5488e88bdb..97074903394704e47199d8c79752da626225f5d2 100644 (file)
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -392,6 +392,29 @@ could fill in the parameters like this:
     if ((p = OSSL_PARAM_locate(params, "cookie")) != NULL)
         OSSL_PARAM_set_utf8_ptr(p, "cookie value");
 
+=head2 Example 3
+
+This example shows a special case where
+I<-Wincompatible-pointer-types-discards-qualifiers> may be set during
+compilation. The value for I<buf> cannot be a I<const char *> type string. An
+alternative in this case would be to use B<OSSL_PARAM> macro abbreviated calls
+rather than the specific callers which allows you to define the sha1 argument
+as a standard character array (I<char[]>).
+
+For example, this code:
+
+    OSSL_PARAM params[2];
+    params[0] = OSSL_PARAM_construct_utf8_string("digest", "SHA1", 0);
+    params[1] = OSSL_PARAM_construct_end();
+
+Can be made compatible with the following version:
+
+    char sha1[] = "SHA1"; /* sha1 is defined as char[] in this case */
+    OSSL_PARAM params[2];
+
+    params[0] = OSSL_PARAM_construct_utf8_string("digest", sha1, 0);
+    params[1] = OSSL_PARAM_construct_end();
+
 =head1 SEE ALSO
 
 L<openssl-core.h(7)>, L<OSSL_PARAM(3)>