Document the new BIO functions introduced as part of the size_t work

Reviewed-by: Richard Levitte <levitte@openssl.org>

13 files changed, 194 insertions, 73 deletions

diff --git a/doc/man3/BIO_ctrl.pod b/doc/man3/BIO_ctrl.pod
index 17dc6ed903..934d07bb0c 100644
--- a/doc/man3/BIO_ctrl.pod
+++ b/doc/man3/BIO_ctrl.pod
@@ -94,7 +94,7 @@ return the amount of pending data.
 =head1 NOTES
 
 BIO_flush(), because it can write data may return 0 or -1 indicating
-that the call should be retried later in a similar manner to BIO_write().
+that the call should be retried later in a similar manner to BIO_write_ex().
 The BIO_should_retry() call should be used and appropriate action taken
 is the call fails.
 
diff --git a/doc/man3/BIO_f_buffer.pod b/doc/man3/BIO_f_buffer.pod
index 3224710942..9c178ce667 100644
--- a/doc/man3/BIO_f_buffer.pod
+++ b/doc/man3/BIO_f_buffer.pod
@@ -49,7 +49,7 @@ is expanded.
 
 These functions, other than BIO_f_buffer(), are implemented as macros.
 
-Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
+Buffering BIOs implement BIO_gets() by using BIO_read_ex() operations on the
 next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
 possible to provide BIO_gets() functionality if the following BIOs do not
 support it (for example SSL BIOs).
diff --git a/doc/man3/BIO_f_md.pod b/doc/man3/BIO_f_md.pod
index 32f0046751..d7ad04d9d0 100644
--- a/doc/man3/BIO_f_md.pod
+++ b/doc/man3/BIO_f_md.pod
@@ -23,8 +23,8 @@ BIO that digests any data passed through it, it is a BIO wrapper
 for the digest routines EVP_DigestInit(), EVP_DigestUpdate()
 and EVP_DigestFinal().
 
-Any data written or read through a digest BIO using BIO_read() and
-BIO_write() is digested.
+Any data written or read through a digest BIO using BIO_read_ex() and
+BIO_write_ex() is digested.
 
 BIO_gets(), if its B<size> parameter is large enough finishes the
 digest calculation and returns the digest value. BIO_puts() is
diff --git a/doc/man3/BIO_f_ssl.pod b/doc/man3/BIO_f_ssl.pod
index 3f9635ee68..48bc150c06 100644
--- a/doc/man3/BIO_f_ssl.pod
+++ b/doc/man3/BIO_f_ssl.pod
@@ -108,7 +108,7 @@ already been established this call has no effect.
 SSL BIOs are exceptional in that if the underlying transport
 is non blocking they can still request a retry in exceptional
 circumstances. Specifically this will happen if a session
-renegotiation takes place during a BIO_read() operation, one
+renegotiation takes place during a BIO_read_ex() operation, one
 case where this happens is when step up occurs.
 
 The SSL flag SSL_AUTO_RETRY can be
diff --git a/doc/man3/BIO_meth_new.pod b/doc/man3/BIO_meth_new.pod
index bf3316104d..b1deb2adf6 100644
--- a/doc/man3/BIO_meth_new.pod
+++ b/doc/man3/BIO_meth_new.pod
@@ -3,11 +3,12 @@
 =head1 NAME
 
 BIO_get_new_index,
-BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write,
-BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts,
-BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl,
-BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy,
-BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
+BIO_meth_new, BIO_meth_free, BIO_meth_get_read_ex, BIO_meth_set_read_ex,
+BIO_meth_get_write_ex, BIO_meth_set_write_ex, BIO_meth_get_write,
+BIO_meth_set_write, BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts,
+BIO_meth_set_puts, BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl,
+BIO_meth_set_ctrl, BIO_meth_get_create, BIO_meth_set_create,
+BIO_meth_get_destroy, BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,
 BIO_meth_set_callback_ctrl  - Routines to build up BIO methods
 
 =head1 SYNOPSIS
@@ -17,10 +18,19 @@ BIO_meth_set_callback_ctrl  - Routines to build up BIO methods
  int BIO_get_new_index(void);
  BIO_METHOD *BIO_meth_new(int type, const char *name);
  void BIO_meth_free(BIO_METHOD *biom);
+ int (*BIO_meth_get_write_ex(BIO_METHOD *biom)) (BIO *, const char *, size_t,
+                                                 size_t *);
  int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int);
+ int BIO_meth_set_write_ex(BIO_METHOD *biom,
+                           int (*bwrite) (BIO *, const char *, size_t,
+                                          size_t *));
  int BIO_meth_set_write(BIO_METHOD *biom,
                         int (*write) (BIO *, const char *, int));
+ int (*BIO_meth_get_read_ex(BIO_METHOD *biom)) (BIO *, char *, size_t,
+                                                size_t *);
  int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int);
+ int BIO_meth_set_read_ex(BIO_METHOD *biom,
+                          int (*bread) (BIO *, char *, size_t, size_t *));
  int BIO_meth_set_read(BIO_METHOD *biom,
                        int (*read) (BIO *, char *, int));
  int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *);
@@ -64,15 +74,23 @@ more information.
 BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory
 associated with it.
 
-BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for
-writing arbitrary length data to the BIO respectively. This function will be
-called in response to the application calling BIO_write(). The parameters for
-the function have the same meaning as for BIO_write().
-
-BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for
-reading arbitrary length data from the BIO respectively. This function will be
-called in response to the application calling BIO_read(). The parameters for the
-function have the same meaning as for BIO_read().
+BIO_meth_get_write_ex() and BIO_meth_set_write_ex() get and set the function
+used for writing arbitrary length data to the BIO respectively. This function
+will be called in response to the application calling BIO_write_ex() or
+BIO_write(). The parameters for the function have the same meaning as for
+BIO_write_ex(). Older code may call BIO_meth_get_write() and
+BIO_meth_set_write() instead. Applications should not call both
+BIO_meth_set_write_ex() and BIO_meth_set_write() or call BIO_meth_get_write()
+when the function was set with BIO_meth_set_write_ex().
+
+BIO_meth_get_read_ex() and BIO_meth_set_read_ex() get and set the function used
+for reading arbitrary length data from the BIO respectively. This function will
+be called in response to the application calling BIO_read_ex() or BIO_read().
+The parameters for the function have the same meaning as for BIO_read_ex().
+Older code may call BIO_meth_get_read() and BIO_meth_set_read() instead.
+Applications should not call both BIO_meth_set_read_ex() and BIO_meth_set_read()
+or call BIO_meth_get_read() when the function was set with
+BIO_meth_set_read_ex().
 
 BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for
 writing a NULL terminated string to the BIO respectively. This function will be
@@ -113,7 +131,7 @@ the function have the same meaning as for BIO_callback_ctrl().
 
 =head1 SEE ALSO
 
-L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new>
+L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read_ex>, L<BIO_new>
 
 =head1 HISTORY
 
diff --git a/doc/man3/BIO_read.pod b/doc/man3/BIO_read.pod
index 45871c1be9..6baa075fc2 100644
--- a/doc/man3/BIO_read.pod
+++ b/doc/man3/BIO_read.pod
@@ -2,19 +2,30 @@
 
 =head1 NAME
 
-BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
+BIO_read_ex, BIO_write_ex, BIO_read, BIO_write, BIO_gets, BIO_puts
+- BIO I/O functions
 
 =head1 SYNOPSIS
 
  #include <openssl/bio.h>
 
- int    BIO_read(BIO *b, void *buf, int len);
- int    BIO_gets(BIO *b, char *buf, int size);
- int    BIO_write(BIO *b, const void *buf, int len);
- int    BIO_puts(BIO *b, const char *buf);
+ int BIO_read_ex(BIO *b, void *out, size_t outl, size_t *read);
+ int BIO_write_ex(BIO *b, const void *in, size_t inl, size_t *written);
+
+ int BIO_read(BIO *b, void *buf, int len);
+ int BIO_gets(BIO *b, char *buf, int size);
+ int BIO_write(BIO *b, const void *buf, int len);
+ int BIO_puts(BIO *b, const char *buf);
 
 =head1 DESCRIPTION
 
+BIO_read_ex() attempts to read B<outl> bytes from BIO B<b> and places the data
+in B<out>. If any bytes were successfully read then the number of bytes read is
+stored in B<*read>.
+
+BIO_write_ex() attempts to write B<inl> bytes from B<in> to BIO B<b>. If
+successful then the number of bytes written is stored in B<*written>.
+
 BIO_read() attempts to read B<len> bytes from BIO B<b> and places
 the data in B<buf>.
 
@@ -31,7 +42,10 @@ BIO_puts() attempts to write a NUL-terminated string B<buf> to BIO B<b>.
 
 =head1 RETURN VALUES
 
-All these functions return either the amount of data successfully read or
+BIO_read_ex() and BIO_write_ex() return 1 if data was successfully read or
+written, and 0 otherwise.
+
+All other functions return either the amount of data successfully read or
 written (if the return value is positive) or that no data was successfully
 read or written if the result is 0 or -1. If the return value is -2 then
 the operation is not implemented in the specific BIO type.  The trailing
diff --git a/doc/man3/BIO_s_bio.pod b/doc/man3/BIO_s_bio.pod
index cb46546e21..48c67febd0 100644
--- a/doc/man3/BIO_s_bio.pod
+++ b/doc/man3/BIO_s_bio.pod
@@ -44,10 +44,10 @@ One typical use of BIO pairs is to place TLS/SSL I/O under application control,
 can be used when the application wishes to use a non standard transport for
 TLS/SSL or the normal socket routines are inappropriate.
 
-Calls to BIO_read() will read data from the buffer or request a retry if no
+Calls to BIO_read_ex() will read data from the buffer or request a retry if no
 data is available.
 
-Calls to BIO_write() will place data in the buffer or request a retry if the
+Calls to BIO_write_ex() will place data in the buffer or request a retry if the
 buffer is full.
 
 The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to
@@ -80,9 +80,9 @@ BIO_free() is not called.
 
 BIO_get_write_guarantee() and BIO_ctrl_get_write_guarantee() return the maximum
 length of data that can be currently written to the BIO. Writes larger than this
-value will return a value from BIO_write() less than the amount requested or if the
-buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function
-whereas BIO_get_write_guarantee() is a macro.
+value will return a value from BIO_write_ex() less than the amount requested or
+if the buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a
+function whereas BIO_get_write_guarantee() is a macro.
 
 BIO_get_read_request() and BIO_ctrl_get_read_request() return the
 amount of data requested, or the buffer size if it is less, if the
@@ -111,12 +111,12 @@ it to the underlying transport. This must be done before any normal processing
 (such as calling select() ) due to a request and BIO_should_read() being true.
 
 To see why this is important consider a case where a request is sent using
-BIO_write() and a response read with BIO_read(), this can occur during an
-TLS/SSL handshake for example. BIO_write() will succeed and place data in the write
-buffer. BIO_read() will initially fail and BIO_should_read() will be true. If
-the application then waits for data to be available on the underlying transport
-before flushing the write buffer it will never succeed because the request was
-never sent!
+BIO_write_ex() and a response read with BIO_read_ex(), this can occur during an
+TLS/SSL handshake for example. BIO_write_ex() will succeed and place data in the
+write buffer. BIO_read_ex() will initially fail and BIO_should_read() will be
+true. If the application then waits for data to be available on the underlying
+transport before flushing the write buffer it will never succeed because the
+request was never sent!
 
 BIO_eof() is true if no data is in the peer BIO and the peer BIO has been
 shutdown.
@@ -187,7 +187,7 @@ the peer might be waiting for the data before being able to continue.
 =head1 SEE ALSO
 
 L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>,
-L<BIO_should_retry(3)>, L<BIO_read(3)>
+L<BIO_should_retry(3)>, L<BIO_read_ex(3)>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man3/BIO_s_fd.pod b/doc/man3/BIO_s_fd.pod
index 79c4a5999f..8ebf563cf6 100644
--- a/doc/man3/BIO_s_fd.pod
+++ b/doc/man3/BIO_s_fd.pod
@@ -20,7 +20,7 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
 BIO_s_fd() returns the file descriptor BIO method. This is a wrapper
 round the platforms file descriptor routines such as read() and write().
 
-BIO_read() and BIO_write() read or write the underlying descriptor.
+BIO_read_ex() and BIO_write_ex() read or write the underlying descriptor.
 BIO_puts() is supported but BIO_gets() is not.
 
 If the close flag is set then close() is called on the underlying
@@ -45,10 +45,10 @@ BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
 
 =head1 NOTES
 
-The behaviour of BIO_read() and BIO_write() depends on the behavior of the
+The behaviour of BIO_read_ex() and BIO_write_ex() depends on the behavior of the
 platforms read() and write() calls on the descriptor. If the underlying
 file descriptor is in a non blocking mode then the BIO will behave in the
-manner described in the L<BIO_read(3)> and L<BIO_should_retry(3)>
+manner described in the L<BIO_read_ex(3)> and L<BIO_should_retry(3)>
 manual pages.
 
 File descriptor BIOs should not be used for socket I/O. Use socket BIOs
@@ -81,8 +81,8 @@ This is a file descriptor BIO version of "Hello World":
 =head1 SEE ALSO
 
 L<BIO_seek(3)>, L<BIO_tell(3)>,
-L<BIO_reset(3)>, L<BIO_read(3)>,
-L<BIO_write(3)>, L<BIO_puts(3)>,
+L<BIO_reset(3)>, L<BIO_read_ex(3)>,
+L<BIO_write_ex(3)>, L<BIO_puts(3)>,
 L<BIO_gets(3)>, L<BIO_printf(3)>,
 L<BIO_set_close(3)>, L<BIO_get_close(3)>
 
diff --git a/doc/man3/BIO_s_file.pod b/doc/man3/BIO_s_file.pod
index e19d824290..abbcdb0e53 100644
--- a/doc/man3/BIO_s_file.pod
+++ b/doc/man3/BIO_s_file.pod
@@ -28,7 +28,7 @@ BIO_s_file() returns the BIO file method. As its name implies it
 is a wrapper round the stdio FILE structure and it is a
 source/sink BIO.
 
-Calls to BIO_read() and BIO_write() read and write data to the
+Calls to BIO_read_ex() and BIO_write_ex() read and write data to the
 underlying stream. BIO_gets() and BIO_puts() are supported on file BIOs.
 
 BIO_flush() on a file BIO calls the fflush() function on the wrapped
@@ -142,8 +142,8 @@ occurred this differs from other types of BIO which will typically return
 
 L<BIO_seek(3)>, L<BIO_tell(3)>,
 L<BIO_reset(3)>, L<BIO_flush(3)>,
-L<BIO_read(3)>,
-L<BIO_write(3)>, L<BIO_puts(3)>,
+L<BIO_read_ex(3)>,
+L<BIO_write_ex(3)>, L<BIO_puts(3)>,
 L<BIO_gets(3)>, L<BIO_printf(3)>,
 L<BIO_set_close(3)>, L<BIO_get_close(3)>
 
diff --git a/doc/man3/BIO_s_socket.pod b/doc/man3/BIO_s_socket.pod
index ad0574aee6..781ff247b2 100644
--- a/doc/man3/BIO_s_socket.pod
+++ b/doc/man3/BIO_s_socket.pod
@@ -17,7 +17,7 @@ BIO_s_socket, BIO_new_socket - socket BIO
 BIO_s_socket() returns the socket BIO method. This is a wrapper
 round the platform's socket routines.
 
-BIO_read() and BIO_write() read or write the underlying socket.
+BIO_read_ex() and BIO_write_ex() read or write the underlying socket.
 BIO_puts() is supported but BIO_gets() is not.
 
 If the close flag is set then the socket is shut down and closed
diff --git a/doc/man3/BIO_set_callback.pod b/doc/man3/BIO_set_callback.pod
index 113b416488..6e5656fb73 100644
--- a/doc/man3/BIO_set_callback.pod
+++ b/doc/man3/BIO_set_callback.pod
@@ -2,17 +2,23 @@
 
 =head1 NAME
 
-BIO_set_callback, BIO_get_callback, BIO_set_callback_arg, BIO_get_callback_arg,
-BIO_debug_callback - BIO callback functions
+BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback,
+BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback
+- BIO callback functions
 
 =head1 SYNOPSIS
 
  #include <openssl/bio.h>
 
-
+ typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
+                                    size_t len, int argi,
+                                    long argl, int ret, size_t *processed);
  typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
                                  long argl, long ret);
 
+ void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
+ BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
+
  void BIO_set_callback(BIO *b, BIO_callack_fn cb);
  BIO_callack_fn BIO_get_callback(BIO *b);
  void BIO_set_callback_arg(BIO *b, char *arg);
@@ -23,10 +29,15 @@ BIO_debug_callback - BIO callback functions
 
 =head1 DESCRIPTION
 
-BIO_set_callback() and BIO_get_callback() set and retrieve the BIO callback,
-they are both macros. The callback is called during most high level BIO
-operations. It can be used for debugging purposes to trace operations on
-a BIO or to modify its operation.
+BIO_set_callback_ex() and BIO_get_callback_ex() set and retrieve the BIO
+callback. The callback is called during most high level BIO operations. It can
+be used for debugging purposes to trace operations on a BIO or to modify its
+operation.
+
+BIO_set_callback() and BIO_get_callback() set and retrieve the old format BIO
+callback. New code should not use these functions, but they are retained for
+backwards compatbility. Any callback set via BIO_set_callback_ex() will get
+called in preference to any set by BIO_set_callback().
 
 BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
 used to set and retrieve an argument for use in the callback.
@@ -36,8 +47,9 @@ out information relating to each BIO operation. If the callback
 argument is set it is interpreted as a BIO to send the information
 to, otherwise stderr is used.
 
-BIO_callback_fn() is the type of the callback function. The meaning of each
-argument is described below:
+BIO_callback_fn_ex() is the type of the callback function and BIO_callback_fn()
+is the type of the old format callback function. The meaning of each argument
+is described below:
 
 =over
 
@@ -51,11 +63,22 @@ B<oper> is set to the operation being performed. For some operations
 the callback is called twice, once before and once after the actual
 operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
 
+=item B<len>
+
+The length of the data requested to be read or written. This is only useful if
+B<oper> is BIO_CB_READ, BIO_CB_WRITE or BIO_CB_GETS.
+
 =item B<argp> B<argi> B<argl>
 
 The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
 the value of B<oper>, that is the operation being performed.
 
+=item B<processed>
+
+B<processed> is a pointer to a location which will be updated with the amount of
+data that was actually read or written. Only used for BIO_CB_READ, BIO_CB_WRITE, 
+BIO_CB_GETS and BIO_CB_PUTS.
+
 =item B<ret>
 
 B<ret> is the return value that would be returned to the
@@ -80,37 +103,103 @@ function that is called.
 
 =item B<BIO_free(b)>
 
-callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L) is called before the
-free operation.
+ callback_ex(b, BIO_CB_FREE, NULL, 0, 0, 0L, 1L, NULL)
+
+or
+
+ callback(b, BIO_CB_FREE, NULL, 0L, 0L, 1L)
+
+is called before the free operation.
+
+=item B<BIO_read_ex(b, out, outl, read)>
 
-=item B<BIO_read(b, out, outl)>
+ callback_ex(b, BIO_CB_READ, out, outl, 0, 0L, 1L, read)
+
+or
+
+ callback(b, BIO_CB_READ, out, outl, 0L, 1L)
+ 
+is called before the read and
+
+ callback_ex(b, BIO_CB_READ | BIO_CB_RETURN, out, outl, 0, 0L, retvalue, read)
+
+or
+
+ callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
 
-callback(b, BIO_CB_READ, out, outl, 0L, 1L) is called before
-the read and callback(b, BIO_CB_READ|BIO_CB_RETURN, out, outl, 0L, retvalue)
 after.
 
-=item B<BIO_write(b, in, inl)>
+=item B<BIO_write(b, in, inl, written)>
+
+ callback_ex(b, BIO_CB_WRITE, in, inl, 0, 0L, 1L, written)
+
+or
+
+ callback(b, BIO_CB_WRITE, in, inl, 0L, 1L)
+
+is called before the write and
+
+ callback_ex(b, BIO_CB_WRITE | BIO_CB_RETURN, in, inl, 0, 0L, retvalue, written)
+
+or
+
+ callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
 
-callback(b, BIO_CB_WRITE, in, inl, 0L, 1L) is called before
-the write and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, inl, 0L, retvalue)
 after.
 
 =item B<BIO_gets(b, out, outl)>
 
-callback(b, BIO_CB_GETS, out, outl, 0L, 1L) is called before
-the operation and callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
+ callback_ex(b, BIO_CB_GETS, out, outl, 0, 0L, 1, NULL, NULL)
+
+or
+
+ callback(b, BIO_CB_GETS, out, outl, 0L, 1L)
+
+is called before the operation and
+
+ callback_ex(b, BIO_CB_GETS | BIO_CB_RETURN, out, outl, 0, 0L, retvalue, read)
+
+or
+
+ callback(b, BIO_CB_GETS|BIO_CB_RETURN, out, outl, 0L, retvalue)
+
 after.
 
 =item B<BIO_puts(b, in)>
 
-callback(b, BIO_CB_WRITE, in, 0, 0L, 1L) is called before
-the operation and callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
+ callback_ex(b, BIO_CB_PUTS, in, 0, 0, 0L, 1L, NULL);
+
+or
+
+ callback(b, BIO_CB_PUTS, in, 0, 0L, 1L)
+
+is called before the operation and
+
+ callback_ex(b, BIO_CB_PUTS | BIO_CB_RETURN, in, 0, 0, 0L, retvalue, written)
+
+or
+
+ callback(b, BIO_CB_WRITE|BIO_CB_RETURN, in, 0, 0L, retvalue)
+
 after.
 
 =item B<BIO_ctrl(BIO *b, int cmd, long larg, void *parg)>
 
-callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L) is called before the call and
-callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret) after.
+ callback_ex(b, BIO_CB_CTRL, parg, 0, cmd, larg, 1L, NULL)
+
+or
+
+ callback(b, BIO_CB_CTRL, parg, cmd, larg, 1L)
+
+is called before the call and
+
+ callback_ex(b, BIO_CB_CTRL | BIO_CB_RETURN, parg, 0, cmd, larg, ret, NULL)
+
+or
+
+ callback(b, BIO_CB_CTRL|BIO_CB_RETURN, parg, cmd, larg, ret)
+ 
+after.
 
 =back
 
diff --git a/doc/man3/BIO_should_retry.pod b/doc/man3/BIO_should_retry.pod
index d6ddf48e2c..d145bf4b26 100644
--- a/doc/man3/BIO_should_retry.pod
+++ b/doc/man3/BIO_should_retry.pod
@@ -24,7 +24,7 @@ functions
 =head1 DESCRIPTION
 
 These functions determine why a BIO is not able to read or write data.
-They will typically be called after a failed BIO_read() or BIO_write()
+They will typically be called after a failed BIO_read_ex() or BIO_write_ex()
 call.
 
 BIO_should_retry() is true if the call that produced this condition
@@ -65,7 +65,7 @@ BIO_retry_type(), and BIO_should_retry(), are implemented as macros.
 
 If BIO_should_retry() returns false then the precise "error condition"
 depends on the BIO type that caused it and the return code of the BIO
-operation. For example if a call to BIO_read() on a socket BIO returns
+operation. For example if a call to BIO_read_ex() on a socket BIO returns
 0 and BIO_should_retry() is false then the cause will be that the
 connection closed. A similar condition on a file BIO will mean that it
 has reached EOF. Some BIO types may place additional information on
diff --git a/doc/man7/bio.pod b/doc/man7/bio.pod
index ec0d2df2c2..7ad8bf45f2 100644
--- a/doc/man7/bio.pod
+++ b/doc/man7/bio.pod
@@ -66,7 +66,7 @@ L<BIO_f_cipher(3)>, L<BIO_f_md(3)>,
 L<BIO_f_null(3)>, L<BIO_f_ssl(3)>,
 L<BIO_find_type(3)>, L<BIO_new(3)>,
 L<BIO_new_bio_pair(3)>,
-L<BIO_push(3)>, L<BIO_read(3)>,
+L<BIO_push(3)>, L<BIO_read_ex(3)>,
 L<BIO_s_accept(3)>, L<BIO_s_bio(3)>,
 L<BIO_s_connect(3)>, L<BIO_s_fd(3)>,
 L<BIO_s_file(3)>, L<BIO_s_mem(3)>,