OSSL_HTTP_REQ_CTX.pod: clarify that resulting BIO must not be freed

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

diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod
index 0c270780e188abea6f79ac101164b0a029f900da..ad2d731153502ceb0cc9683ac545608b330c0740 100644 (file)
--- a/doc/man3/OSSL_HTTP_REQ_CTX.pod
+++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod
@@ -139,13 +139,15 @@ using the ASN.1 template I<it> and places the result in I<*pval>.
 
 OSSL_HTTP_REQ_CTX_exchange() calls OSSL_HTTP_REQ_CTX_nbio() as often as needed
 in order to exchange a request and response or until a timeout is reached.
-If successful and an ASN.1-encoded response was expected, the response contents
-should be read via the BIO returned by OSSL_HTTP_REQ_CTX_get0_mem_bio().
-Else the I<rbio> that was given when calling OSSL_HTTP_REQ_CTX_new()
-represents the current state of reading the response.
-If OSSL_HTTP_REQ_CTX_exchange() was successful, this BIO has been read past the
-end of the response headers, such that the actual response contents can be read
-via this BIO, which may support streaming.
+On success it returns a pointer to the BIO that can be used to read the result.
+If an ASN.1-encoded response was expected, this is the BIO
+returned by OSSL_HTTP_REQ_CTX_get0_mem_bio() when called after the exchange.
+This memory BIO does not support streaming.
+Otherwise it may be the I<rbio> given when calling OSSL_HTTP_REQ_CTX_new(),
+and this BIO has been read past the end of the response headers,
+such that the actual response body can be read via this BIO,
+which may support streaming.
+The returned BIO pointer must not be freed by the caller.
 
 OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
 Before sending the request, this could used to modify the HTTP request text.
@@ -153,6 +155,7 @@ I<Use with caution!>
 After receiving a response via HTTP, the BIO represents the current state of
 reading the response headers. If the response was expected to be ASN.1 encoded,
 its contents can be read via this BIO, which does not support streaming.
+The returned BIO pointer must not be freed by the caller.
 
 OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents
 in I<rctx> if provided by the server as <Content-Length> header field, else 0.
@@ -227,6 +230,7 @@ return 1 for success, 0 on error or redirection, -1 if retry is needed.
 
 OSSL_HTTP_REQ_CTX_exchange() and OSSL_HTTP_REQ_CTX_get0_mem_bio()
 return a pointer to a B<BIO> on success and NULL on failure.
+The returned BIO must not be freed by the caller.
 
 OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents
 or 0 if not available or an error occurred.