1*2175Sjp161948=pod 2*2175Sjp161948 3*2175Sjp161948=head1 NAME 4*2175Sjp161948 5*2175Sjp161948BIO_should_retry, BIO_should_read, BIO_should_write, 6*2175Sjp161948BIO_should_io_special, BIO_retry_type, BIO_should_retry, 7*2175Sjp161948BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions 8*2175Sjp161948 9*2175Sjp161948=head1 SYNOPSIS 10*2175Sjp161948 11*2175Sjp161948 #include <openssl/bio.h> 12*2175Sjp161948 13*2175Sjp161948 #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ) 14*2175Sjp161948 #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE) 15*2175Sjp161948 #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL) 16*2175Sjp161948 #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS) 17*2175Sjp161948 #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY) 18*2175Sjp161948 19*2175Sjp161948 #define BIO_FLAGS_READ 0x01 20*2175Sjp161948 #define BIO_FLAGS_WRITE 0x02 21*2175Sjp161948 #define BIO_FLAGS_IO_SPECIAL 0x04 22*2175Sjp161948 #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL) 23*2175Sjp161948 #define BIO_FLAGS_SHOULD_RETRY 0x08 24*2175Sjp161948 25*2175Sjp161948 BIO * BIO_get_retry_BIO(BIO *bio, int *reason); 26*2175Sjp161948 int BIO_get_retry_reason(BIO *bio); 27*2175Sjp161948 28*2175Sjp161948=head1 DESCRIPTION 29*2175Sjp161948 30*2175Sjp161948These functions determine why a BIO is not able to read or write data. 31*2175Sjp161948They will typically be called after a failed BIO_read() or BIO_write() 32*2175Sjp161948call. 33*2175Sjp161948 34*2175Sjp161948BIO_should_retry() is true if the call that produced this condition 35*2175Sjp161948should then be retried at a later time. 36*2175Sjp161948 37*2175Sjp161948If BIO_should_retry() is false then the cause is an error condition. 38*2175Sjp161948 39*2175Sjp161948BIO_should_read() is true if the cause of the condition is that a BIO 40*2175Sjp161948needs to read data. 41*2175Sjp161948 42*2175Sjp161948BIO_should_write() is true if the cause of the condition is that a BIO 43*2175Sjp161948needs to read data. 44*2175Sjp161948 45*2175Sjp161948BIO_should_io_special() is true if some "special" condition, that is a 46*2175Sjp161948reason other than reading or writing is the cause of the condition. 47*2175Sjp161948 48*2175Sjp161948BIO_get_retry_reason() returns a mask of the cause of a retry condition 49*2175Sjp161948consisting of the values B<BIO_FLAGS_READ>, B<BIO_FLAGS_WRITE>, 50*2175Sjp161948B<BIO_FLAGS_IO_SPECIAL> though current BIO types will only set one of 51*2175Sjp161948these. 52*2175Sjp161948 53*2175Sjp161948BIO_get_retry_BIO() determines the precise reason for the special 54*2175Sjp161948condition, it returns the BIO that caused this condition and if 55*2175Sjp161948B<reason> is not NULL it contains the reason code. The meaning of 56*2175Sjp161948the reason code and the action that should be taken depends on 57*2175Sjp161948the type of BIO that resulted in this condition. 58*2175Sjp161948 59*2175Sjp161948BIO_get_retry_reason() returns the reason for a special condition if 60*2175Sjp161948passed the relevant BIO, for example as returned by BIO_get_retry_BIO(). 61*2175Sjp161948 62*2175Sjp161948=head1 NOTES 63*2175Sjp161948 64*2175Sjp161948If BIO_should_retry() returns false then the precise "error condition" 65*2175Sjp161948depends on the BIO type that caused it and the return code of the BIO 66*2175Sjp161948operation. For example if a call to BIO_read() on a socket BIO returns 67*2175Sjp1619480 and BIO_should_retry() is false then the cause will be that the 68*2175Sjp161948connection closed. A similar condition on a file BIO will mean that it 69*2175Sjp161948has reached EOF. Some BIO types may place additional information on 70*2175Sjp161948the error queue. For more details see the individual BIO type manual 71*2175Sjp161948pages. 72*2175Sjp161948 73*2175Sjp161948If the underlying I/O structure is in a blocking mode almost all current 74*2175Sjp161948BIO types will not request a retry, because the underlying I/O 75*2175Sjp161948calls will not. If the application knows that the BIO type will never 76*2175Sjp161948signal a retry then it need not call BIO_should_retry() after a failed 77*2175Sjp161948BIO I/O call. This is typically done with file BIOs. 78*2175Sjp161948 79*2175Sjp161948SSL BIOs are the only current exception to this rule: they can request a 80*2175Sjp161948retry even if the underlying I/O structure is blocking, if a handshake 81*2175Sjp161948occurs during a call to BIO_read(). An application can retry the failed 82*2175Sjp161948call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY 83*2175Sjp161948on the underlying SSL structure. 84*2175Sjp161948 85*2175Sjp161948While an application may retry a failed non blocking call immediately 86*2175Sjp161948this is likely to be very inefficient because the call will fail 87*2175Sjp161948repeatedly until data can be processed or is available. An application 88*2175Sjp161948will normally wait until the necessary condition is satisfied. How 89*2175Sjp161948this is done depends on the underlying I/O structure. 90*2175Sjp161948 91*2175Sjp161948For example if the cause is ultimately a socket and BIO_should_read() 92*2175Sjp161948is true then a call to select() may be made to wait until data is 93*2175Sjp161948available and then retry the BIO operation. By combining the retry 94*2175Sjp161948conditions of several non blocking BIOs in a single select() call 95*2175Sjp161948it is possible to service several BIOs in a single thread, though 96*2175Sjp161948the performance may be poor if SSL BIOs are present because long delays 97*2175Sjp161948can occur during the initial handshake process. 98*2175Sjp161948 99*2175Sjp161948It is possible for a BIO to block indefinitely if the underlying I/O 100*2175Sjp161948structure cannot process or return any data. This depends on the behaviour of 101*2175Sjp161948the platforms I/O functions. This is often not desirable: one solution 102*2175Sjp161948is to use non blocking I/O and use a timeout on the select() (or 103*2175Sjp161948equivalent) call. 104*2175Sjp161948 105*2175Sjp161948=head1 BUGS 106*2175Sjp161948 107*2175Sjp161948The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: 108*2175Sjp161948that is they cannot retry after a partial read or write. This is usually 109*2175Sjp161948worked around by only passing the relevant data to ASN1 functions when 110*2175Sjp161948the entire structure can be read or written. 111*2175Sjp161948 112*2175Sjp161948=head1 SEE ALSO 113*2175Sjp161948 114*2175Sjp161948TBA 115