From: Ryan Schanzenbacher <ryan@rschanz.org>
Date: Sat, 8 Mar 2025 04:35:32 +0000 (-0500)
Subject: docs: update OSSL_PARAM_int documentation
X-Git-Tag: openssl-3.0.17~59
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=07ebb20eb67d241df1ecdc32f7036b2f54adf49d;p=thirdparty%2Fopenssl.git

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 22fd0f0d7dd..405a0dd928c 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 105fe3241f8..996872f2bed 100644
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -393,6 +393,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)>