BIO_seed() and BIO_tell() were documented in two other documents,

[openssl.git] / doc / crypto / BIO_should_retry.pod

diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod
index a4c464ffa14a3ca112dc28eaa32fcd807a3e64c2..539c3912728caebc5e77bfcadf583e52f061cc92 100644 (file)
--- a/doc/crypto/BIO_should_retry.pod
+++ b/doc/crypto/BIO_should_retry.pod
@@ -2,7 +2,9 @@
 
 =head1 NAME
 
 
 =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
 
 
 =head1 SYNOPSIS
 


@@ -46,7 +48,7 @@ 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
 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
 BIO_get_retry_reason() 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 
 
 BIO_get_retry_BIO() determines the precise reason for the special
 condition, it returns the BIO that caused this condition and if 


@@ -55,7 +57,7 @@ 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
 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
 
 
 =head1 NOTES
 


@@ -68,53 +70,34 @@ has reached EOF. Some BIO types may place additional information on
 the error queue. For more details see the individual BIO type manual
 pages.
 
 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.
 
 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
 
 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
 
 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
 
 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.
 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.