X-Git-Url: https://git.openssl.org/gitweb/?p=openssl.git;a=blobdiff_plain;f=doc%2Fcrypto%2FBIO_should_retry.pod;h=b6d51f719d44ccdf0da1edd7d58fa55d898a4be7;hp=a4c464ffa14a3ca112dc28eaa32fcd807a3e64c2;hb=ae551760917614647ad6fbacec6e4c1b495a94cf;hpb=d7b9c76c72bd6e744db2070d148738941ba38305 diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod index a4c464ffa1..b6d51f719d 100644 --- a/doc/crypto/BIO_should_retry.pod +++ b/doc/crypto/BIO_should_retry.pod @@ -2,7 +2,9 @@ =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 @@ -43,10 +45,10 @@ 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_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, B, B 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 @@ -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 -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 @@ -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. -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.