Commit 83ef5622a6 for openssl.org

commit 83ef5622a64d34885a7d6da866accf2281879c7d
Author: Michael Richardson <mcr@sandelman.ca>
Date:   Fri Sep 5 14:56:36 2025 -0400

    d2i_* docs: clarify how reuse is used, and how to set libctx and propq

    Also removed BUGS section

    Reviewed-by: David von Oheimb <david.von.oheimb@siemens.com>
    Reviewed-by: Eugene Syromiatnikov <esyr@openssl.org>
    MergeDate: Thu May 21 09:14:32 2026
    (Merged from https://github.com/openssl/openssl/pull/28456)

diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 41e76ae837..53f5aaacb7 100644
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -471,21 +471,29 @@ encoding.  Unlike the C structures which can have pointers to sub-objects
 within, the DER is a serialized encoding, suitable for sending over the
 network, writing to a file, and so on.

-B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a
-pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to
-the byte following the parsed data.  If I<a> is not NULL then a pointer
-to the returned structure is also written to I<*a>.  If an error occurred
-then NULL is returned. The caller retains ownership of the
-returned object and needs to free it when it is no longer needed, e.g.
-using X509_free() for X509 objects or DSA_SIG_free() for DSA_SIG objects.
-
-On a successful return, if I<*a> is not NULL then it is assumed that I<*a>
-contains a valid B<I<TYPE>> structure and an attempt is made to reuse it.
-For B<I<TYPE>> structures where it matters it is possible to set up a library
-context on the decoded structure this way (see the B<EXAMPLES> section).
-However using the "reuse" capability for other purposes is B<strongly
-discouraged> (see B<BUGS> below, and the discussion in the B<RETURN VALUES>
-section).
+B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>.
+When there is no error, a pointer to a B<I<TYPE>> object is returned and I<*ppin> is
+incremented to the byte following the parsed data.
+The caller owns the returned object and needs to free it when it is no longer needed,
+e.g., via X509_free() for B<X509> objects.
+
+If either I<a> or I<*a> is NULL, then fresh storage is allocated for the
+returned object, and if I<a> is not NULL then I<*a> is set equal to the
+returned pointer.
+
+When both I<a> and I<*a> are not NULL, I<*a> MUST be a pointer to an
+existing I<TYPE> object, which is reused to hold the decoded result.
+On error (NULL return value), the object is freed and I<*a> is set to NULL.
+
+From OpenSSL 3.x onwards, reuse is only supported when I<*a> points to a newly
+allocated, and not otherwise modified, I<TYPE> object.
+Allocation can be via one of the various _ex() routines, which make it possible
+to associate the allocated object with a chosen I<libctx> (library context)
+or I<propq> (property query), see the B<EXAMPLES> section.
+No other reuse is supported (see B<BUGS> below, and the discussion in the
+B<RETURN VALUES> section).
+The returned object is not suitable for another reuse: each reuse attempt MUST
+start with a newly allocated object.

 B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts
 to parse data from BIO I<bp>.