8162f6f58a
Also fix typo noted on GitHub. Suppport typedef and #define to find-doc-nits Reviewed-by: Richard Levitte <levitte@openssl.org>
135 lines
5.3 KiB
Text
135 lines
5.3 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
BIO_should_read, BIO_should_write,
|
|
BIO_should_io_special, BIO_retry_type, BIO_should_retry,
|
|
BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
|
|
functions
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/bio.h>
|
|
|
|
#define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
|
|
#define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
|
|
#define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
|
|
#define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
|
|
#define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
|
|
|
|
#define BIO_FLAGS_READ 0x01
|
|
#define BIO_FLAGS_WRITE 0x02
|
|
#define BIO_FLAGS_IO_SPECIAL 0x04
|
|
#define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
|
|
#define BIO_FLAGS_SHOULD_RETRY 0x08
|
|
|
|
BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
|
|
int BIO_get_retry_reason(BIO *bio);
|
|
void BIO_set_retry_reason(BIO *bio, int reason);
|
|
|
|
=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()
|
|
call.
|
|
|
|
BIO_should_retry() is true if the call that produced this condition
|
|
should then be retried at a later time.
|
|
|
|
If BIO_should_retry() is false then the cause is an error condition.
|
|
|
|
BIO_should_read() is true if the cause of the condition is that a BIO
|
|
needs to read data.
|
|
|
|
BIO_should_write() is true if the cause of the condition is that a BIO
|
|
needs to read data.
|
|
|
|
BIO_should_io_special() is true if some "special" condition, that is a
|
|
reason other than reading or writing is the cause of the condition.
|
|
|
|
BIO_retry_type() returns a mask of the cause of a retry condition
|
|
consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>,
|
|
B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of
|
|
these.
|
|
|
|
BIO_get_retry_BIO() determines the precise reason for the special
|
|
condition, it returns the BIO that caused this condition and if
|
|
B<reason> is not NULL it contains the reason code. The meaning of
|
|
the reason code and the action that should be taken depends on
|
|
the type of BIO that resulted in this condition.
|
|
|
|
BIO_get_retry_reason() returns the reason for a special condition if
|
|
passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
|
|
|
|
BIO_set_retry_reason() sets the retry reason for a special condition for a given
|
|
BIO. This would usually only be called by BIO implementations.
|
|
|
|
=head1 NOTES
|
|
|
|
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
|
|
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
|
|
the error queue. For more details see the individual BIO type manual
|
|
pages.
|
|
|
|
If the underlying I/O structure is in a blocking mode almost all current
|
|
BIO types will not request a retry, because the underlying I/O
|
|
calls will not. If the application knows that the BIO type will never
|
|
signal a retry then it need not call BIO_should_retry() after a failed
|
|
BIO I/O call. This is typically done with file BIOs.
|
|
|
|
SSL BIOs are the only current exception to this rule: they can request a
|
|
retry even if the underlying I/O structure is blocking, if a handshake
|
|
occurs during a call to BIO_read(). An application can retry the failed
|
|
call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
|
|
on the underlying SSL structure.
|
|
|
|
While an application may retry a failed non blocking call immediately
|
|
this is likely to be very inefficient because the call will fail
|
|
repeatedly until data can be processed or is available. An application
|
|
will normally wait until the necessary condition is satisfied. How
|
|
this is done depends on the underlying I/O structure.
|
|
|
|
For example if the cause is ultimately a socket and BIO_should_read()
|
|
is true then a call to select() may be made to wait until data is
|
|
available and then retry the BIO operation. By combining the retry
|
|
conditions of several non blocking BIOs in a single select() call
|
|
it is possible to service several BIOs in a single thread, though
|
|
the performance may be poor if SSL BIOs are present because long delays
|
|
can occur during the initial handshake process.
|
|
|
|
It is possible for a BIO to block indefinitely if the underlying I/O
|
|
structure cannot process or return any data. This depends on the behaviour of
|
|
the platforms I/O functions. This is often not desirable: one solution
|
|
is to use non blocking I/O and use a timeout on the select() (or
|
|
equivalent) call.
|
|
|
|
=head1 BUGS
|
|
|
|
The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
|
|
that is they cannot retry after a partial read or write. This is usually
|
|
worked around by only passing the relevant data to ASN1 functions when
|
|
the entire structure can be read or written.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<bio>
|
|
|
|
=head1 HISTORY
|
|
|
|
The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in
|
|
OpenSSL version 1.1.0.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the OpenSSL license (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|