1 files changed, 19 insertions, 23 deletions
diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index 6da1d91b9f37..eaa0986666fc 100644
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -62,6 +62,7 @@ for connecting to the given server and the optionally given I<port>,
 defaulting to 80 for HTTP or 443 for HTTPS.
 Then this internal BIO is used for setting up a connection
 and for exchanging one or more request and response.
+
 If I<bio> is given and I<rbio> is NULL then this I<bio> is used instead.
 If both I<bio> and I<rbio> are given (which may be memory BIOs for instance)
 then no explicit connection is set up, but
@@ -69,7 +70,8 @@ I<bio> is used for writing requests and I<rbio> for reading responses.
 As soon as the client has flushed I<bio> the server must be ready to provide
 a response or indicate a waiting condition via I<rbio>.
 
-If I<bio> is given, it is an error to provide I<proxy> or I<no_proxy> arguments,
+If I<bio> is given,
+it is an error to provide non-NULL I<proxy> or I<no_proxy> arguments,
 while I<server> and I<port> arguments may be given to support diagnostic output.
 If I<bio> is NULL the optional I<proxy> parameter can be used to set an
 HTTP(S) proxy to use (unless overridden by "no_proxy" settings).
@@ -101,8 +103,8 @@ I<bio_update_fn> is a BIO connect/disconnect callback function with prototype
  BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
 
 The callback function may modify the BIO provided in the I<bio> argument,
-whereby it may make use of a custom defined argument I<arg>,
-which may for instance point to an B<SSL_CTX> structure.
+whereby it may use an optional custom defined argument I<arg>,
+which can for instance point to an B<SSL_CTX> structure.
 During connection establishment, just after calling BIO_do_connect_retry(), the
 callback function is invoked with the I<connect> argument being 1 and
 I<detail> being 1 if I<use_ssl> is nonzero (i.e., HTTPS is requested), else 0.
@@ -110,7 +112,7 @@ On disconnect I<connect> is 0 and I<detail> is 1 if no error occurred, else 0.
 For instance, on connect the callback may push an SSL BIO to implement HTTPS;
 after disconnect it may do some diagnostic output and pop and free the SSL BIO.
 
-The callback function must return either the potentially modified BIO I<bio>.
+The callback function must return either the potentially modified BIO I<bio>
 or NULL to indicate failure, in which case it should not modify the BIO.
 
 Here is a simple example that supports TLS connections (but not via a proxy):
@@ -137,6 +139,8 @@ Here is a simple example that supports TLS connections (but not via a proxy):
  }
 
 After disconnect the modified BIO will be deallocated using BIO_free_all().
+The optional callback function argument I<arg> is not consumed,
+so must be freed by the caller when not needed any more.
 
 The I<buf_size> parameter specifies the response header maximum line length.
 A value <= 0 means that the B<OSSL_HTTP_DEFAULT_MAX_LINE_LEN> (4KiB) is used.
@@ -174,24 +178,10 @@ else HTTP POST with the contents of I<req> and optional I<content_type>, where
 the length of the data in I<req> does not need to be determined in advance: the
 BIO will be read on-the-fly while sending the request, which supports streaming.
 The optional list I<headers> may contain additional custom HTTP header lines.
-If the parameter I<expected_content_type>
-is not NULL then the client will check that the given content type string
-is included in the HTTP header of the response and return an error if not.
-If the I<expect_asn1> parameter is nonzero,
-a structure in ASN.1 encoding will be expected as response content.
 The I<max_resp_len> parameter specifies the maximum allowed
 response content length, where the value 0 indicates no limit.
-If the I<timeout> parameter is > 0 this indicates the maximum number of seconds
-the subsequent HTTP transfer (sending the request and receiving a response)
-is allowed to take.
-A value of 0 enables waiting indefinitely, i.e., no timeout.
-A value < 0 indicates that the I<overall_timeout> parameter value given
-when opening the HTTP transfer will be used instead.
-If I<keep_alive> is 0 the connection is not kept open
-after receiving a response, which is the default behavior for HTTP 1.0.
-If the value is 1 or 2 then a persistent connection is requested.
-If the value is 2 then a persistent connection is required,
-i.e., an error occurs in case the server does not grant it.
+For the meaning of the I<expected_content_type>, I<expect_asn1>, I<timeout>,
+and I<keep_alive> parameters, see L<OSSL_HTTP_REQ_CTX_set_expected(3)>.
 
 OSSL_HTTP_exchange() exchanges any form of HTTP request and response
 as specified by I<rctx>, which must include both connection and request data,
@@ -202,7 +192,7 @@ is not NULL the latter pointer is used to provide any new location that
 the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND).
 In this case the function returns NULL and the caller is
 responsible for deallocating the URL with L<OPENSSL_free(3)>.
-If the response header contains one or more "Content-Length" header lines and/or
+If the response header contains one or more C<Content-Length> lines and/or
 an ASN.1-encoded response is expected, which should include a total length,
 the length indications received are checked for consistency
 and for not exceeding any given maximum response length.
@@ -250,6 +240,10 @@ C<http_proxy>, C<HTTP_PROXY>, C<https_proxy>, C<HTTPS_PROXY>, C<no_proxy>, and
 C<NO_PROXY>, have been chosen for maximal compatibility with
 other HTTP client implementations such as wget, curl, and git.
 
+When built with tracing enabled, OSSL_HTTP_transfer() and all functions using it
+may be traced using B<OSSL_TRACE_CATEGORY_HTTP>.
+See also L<OSSL_trace_enabled(3)> and L<openssl-env(7)>.
+
 =head1 RETURN VALUES
 
 OSSL_HTTP_open() returns on success a B<OSSL_HTTP_REQ_CTX>, else NULL.
@@ -271,7 +265,9 @@ OSSL_HTTP_close() returns 0 if anything went wrong while disconnecting, else 1.
 
 L<OSSL_HTTP_parse_url(3)>, L<BIO_new_connect(3)>,
 L<ASN1_item_i2d_mem_bio(3)>, L<ASN1_item_d2i_bio(3)>,
-L<OSSL_HTTP_is_alive(3)>
+L<OSSL_HTTP_REQ_CTX_set_expected(3)>,
+L<OSSL_HTTP_is_alive(3)>,
+L<OSSL_trace_enabled(3)>, and L<openssl-env(7)>.
 
 =head1 HISTORY
 
@@ -279,7 +275,7 @@ All the functions described here were added in OpenSSL 3.0.
 
 =head1 COPYRIGHT
 
-Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy