Commit b83b67fe59 for openssl.org

commit b83b67fe59511de951db1987fb2ab9e028e2da32
Author: Ryan Schanzenbacher <ryan@rschanz.org>
Date:   Fri Mar 7 23:35:32 2025 -0500

    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)

diff --git a/doc/man3/OSSL_PARAM.pod b/doc/man3/OSSL_PARAM.pod
index 22fd0f0d7d..405a0dd928 100644
--- 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 8de0e86b7a..23ef0c0d07 100644
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -402,6 +402,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)>