=head1 NAME
- BIO_should_retry, BIO_should_read, BIO_should_write - BIO retry functions
+BIO_should_retry, 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 retry functions
=head1 SYNOPSIS
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_get_retry_reason() returns a mask of the cause of a retry 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 (Q: is this correct?).
+these.
BIO_get_retry_BIO() determines the precise reason for the special
condition, it returns the BIO that caused this condition and if
the type of BIO that resulted in this condition.
BIO_get_retry_reason() returns the reason for a special condition if
-pass the relevant BIO, for example as returned by BIO_get_retry_BIO().
+passed the relevant BIO, for example as returned by BIO_get_retry_BIO().
=head1 NOTES
the error queue. For more details see the individual BIO type manual
pages.
-If the underlying I/O structure is in a blocking mode then most BIO
-types will not signal a retry condition, because the underlying I/O
+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.
-The presence of an SSL BIO is an exception to this rule: it can
-request a retry because the handshake process is underway (either
-initially or due to a session renegotiation) even if the underlying
-I/O structure (for example a socket) is in a blocking mode.
-
-The action an application should take after a BIO has signalled that a
-retry is required depends on the BIO that caused the retry.
-
-If the underlying I/O structure is in a blocking mode then the BIO
-call can be retried immediately. That is something like this can be
-done:
-
- do {
- len = BIO_read(bio, buf, len);
- } while((len <= 0) && BIO_should_retry(bio));
+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 is likely to
-fail repeatedly until data can be processed. An application will normally
-wait until the necessary condition is satisfied. How this is done depends
-on the underlying I/O structure.
+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.
-
-The cause of the retry condition may not be the same as the call that
-made it: for example if BIO_write() fails BIO_should_read() can be
-true. One possible reason for this is that an SSL handshake is taking
-place.
-
-Even if data is read from the underlying I/O structure this does not
-imply that the next BIO I/O call will succeed. For example if an
-encryption BIO reads only a fraction of a block it will not be
-able to pass any data to the application until a complete block has
-been read.
+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 the data. This depends on the behaviour of
+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.
projects / openssl.git / blobdiff