doc/man3/X509_STORE_get0_param.pod: mention how to free the returned objects

It is not entirely obvious from the description how the objects returned
by X509_STORE_get1_objects() and X509_STORE_get1_all_certs() are
supposed to be freed, explicitly mention the relevant calls, and provide
a reference to DEFINE_STACK_OF(3).

Signed-off-by: Eugene Syromiatnikov <esyr@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Todd Short <todd.short@me.com>
(Merged from https://github.com/openssl/openssl/pull/29002)

(cherry picked from commit de1abbed1cd75fcb8a6becadbc2854aa124f9bcf)

diff --git a/doc/man3/X509_STORE_get0_param.pod b/doc/man3/X509_STORE_get0_param.pod
index 95a1725bc3881472a8387fca9cf15c152e453bbb..794b149e661642a90cb208e37fe9468ed7449919 100644 (file)
--- a/doc/man3/X509_STORE_get0_param.pod
+++ b/doc/man3/X509_STORE_get0_param.pod
@@ -25,8 +25,9 @@ parameters for I<xs>. The returned pointer must not be freed by the
 calling application
 
 X509_STORE_get1_objects() returns a snapshot of all objects in the store's X509
-cache. The cache contains B<X509> and B<X509_CRL> objects. The caller is
-responsible for freeing the returned list.
+cache. The cache contains B<X509> and B<X509_CRL> objects. The caller
+is responsible for freeing the returned list,
+using sk_X509_OBJECT_pop_free(sk, X509_OBJECT_free).
 
 X509_STORE_get0_objects() retrieves an internal pointer to the store's
 X509 object cache. The cache contains B<X509> and B<X509_CRL> objects. The
@@ -35,7 +36,8 @@ shared across multiple threads, it is not safe to use the result of this
 function. Use X509_STORE_get1_objects() instead, which avoids this problem.
 
 X509_STORE_get1_all_certs() returns a list of all certificates in the store.
-The caller is responsible for freeing the returned list.
+The caller is responsible for freeing the returned list
+with OSSL_STACK_OF_X509_free().
 
 =head1 RETURN VALUES
 
@@ -54,6 +56,7 @@ certificates on success, else NULL.
 
 =head1 SEE ALSO
 
+L<DEFINE_STACK_OF(3)>,
 L<X509_STORE_new(3)>
 
 =head1 HISTORY