=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.
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).
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
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
=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
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 *);
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
=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
=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>.
=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
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
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
(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.
=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
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
=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
=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)>
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
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)>
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
=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);
=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.
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
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
=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
=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
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
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)>,
projects / openssl.git / commitdiff