From: Ruslan Baratov <x@ruslo.dev>
Date: Thu, 23 May 2024 14:03:12 +0000 (+0800)
Subject: [Docs] Notes about freeing objects
X-Git-Tag: openssl-3.4.0-alpha1~489
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=d4700c0b237c05315e3bf14fc416abcbdfe51ff2;p=thirdparty%2Fopenssl.git

[Docs] Notes about freeing objects

- Free objects returned from PEM read
- Free objects returned from d2i_*

Reviewed-by: Paul Dale <ppzgs1@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/24478)
---

diff --git a/doc/man3/PEM_read_bio_PrivateKey.pod b/doc/man3/PEM_read_bio_PrivateKey.pod
index 6e521b268f0..290a5eef51b 100644
--- a/doc/man3/PEM_read_bio_PrivateKey.pod
+++ b/doc/man3/PEM_read_bio_PrivateKey.pod
@@ -332,7 +332,9 @@ NULL but I<*x> is NULL then the structure returned will be written
 to I<*x>. If neither I<x> nor I<*x> is NULL then an attempt is made
 to reuse the structure at I<*x> (but see BUGS and EXAMPLES sections).
 Irrespective of the value of I<x> a pointer to the structure is always
-returned (or NULL if an error occurred).
+returned (or NULL if an error occurred). 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 EVP_PKEY_free() for EVP_PKEY objects.
 
 The PEM functions which write private keys take an I<enc> parameter
 which specifies the encryption algorithm to use, encryption is done
diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 06f764ef8bb..1c0b5bf6252 100644
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -395,7 +395,9 @@ 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.
+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.