From: Richard Levitte <levitte@openssl.org>
Date: Mon, 16 Aug 2021 10:14:30 +0000 (+0200)
Subject: Correct UTF8 params documentation further
X-Git-Tag: openssl-3.0.0~113
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=43cf27c9a4fe135013dd4127dd4bcf862d1cb503;p=thirdparty%2Fopenssl.git

Correct UTF8 params documentation further

The latest change misdocumented OSSL_PARAM_get_utf8_string(), that
change should have been for OSSL_PARAM_set_utf8_string().

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

diff --git a/doc/man3/OSSL_PARAM_int.pod b/doc/man3/OSSL_PARAM_int.pod
index 8dbe830e957..69b723d3482 100644
--- a/doc/man3/OSSL_PARAM_int.pod
+++ b/doc/man3/OSSL_PARAM_int.pod
@@ -241,15 +241,20 @@ will be assigned the size the parameter's I<data> buffer should have.
 OSSL_PARAM_get_utf8_string() retrieves a UTF8 string from the parameter
 pointed to by I<p>.
 The string is stored into I<*val> with a size limit of I<max_len>,
-which must be large enough to accomodate the string. A terminating NUL byte
-is added only if the buffer is longer than the string length otherwise the
-string will not be NUL terminated.
+which must be large enough to accomodate a terminating NUL byte,
+otherwise this function will fail.
 If I<*val> is NULL, memory is allocated for the string (including the
 terminating  NUL byte) and I<max_len> is ignored.
 If memory is allocated by this function, it must be freed by the caller.
 
 OSSL_PARAM_set_utf8_string() sets a UTF8 string from the parameter pointed to
 by I<p> to the value referenced by I<val>.
+If the parameter's I<data> field isn't NULL, its I<data_size> must indicate
+that the buffer is large enough to accomodate the string that I<val> points at,
+not including the terminating NUL byte, or this function will fail.
+A terminating NUL byte is added only if the parameter's I<data_size> indicates
+the buffer is longer than the string length, otherwise the string will not be
+NUL terminated.
 If the parameter's I<data> field is NULL, then only its I<return_size> field
 will be assigned the minimum size the parameter's I<data> buffer should have
 to accomodate the string, not including a terminating NUL byte.