summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/BIO_should_retry.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/BIO_should_retry.3')
-rw-r--r--src/lib/libcrypto/man/BIO_should_retry.321
1 files changed, 11 insertions, 10 deletions
diff --git a/src/lib/libcrypto/man/BIO_should_retry.3 b/src/lib/libcrypto/man/BIO_should_retry.3
index c06e907235..f512e08b89 100644
--- a/src/lib/libcrypto/man/BIO_should_retry.3
+++ b/src/lib/libcrypto/man/BIO_should_retry.3
@@ -1,6 +1,6 @@
1.\" $OpenBSD: BIO_should_retry.3,v 1.2 2016/11/06 15:52:50 jmc Exp $ 1.\" $OpenBSD: BIO_should_retry.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
2.\" 2.\"
3.Dd $Mdocdate: November 6 2016 $ 3.Dd $Mdocdate: November 7 2016 $
4.Dt BIO_SHOULD_RETRY 3 4.Dt BIO_SHOULD_RETRY 3
5.Os 5.Os
6.Sh NAME 6.Sh NAME
@@ -9,6 +9,7 @@
9.Nm BIO_should_write , 9.Nm BIO_should_write ,
10.Nm BIO_should_io_special , 10.Nm BIO_should_io_special ,
11.Nm BIO_retry_type , 11.Nm BIO_retry_type ,
12.Nm BIO_should_retry ,
12.Nm BIO_get_retry_BIO , 13.Nm BIO_get_retry_BIO ,
13.Nm BIO_get_retry_reason 14.Nm BIO_get_retry_reason
14.Nd BIO retry functions 15.Nd BIO retry functions
@@ -58,8 +59,8 @@ is true if the cause of the condition is that a BIO needs to read data.
58is true if the cause of the condition is that a BIO needs to write data. 59is true if the cause of the condition is that a BIO needs to write data.
59.Pp 60.Pp
60.Fn BIO_should_io_special 61.Fn BIO_should_io_special
61is true if some "special" condition, that is a reason other than 62is true if some "special" condition
62reading or writing, is the cause of the condition. 63(i.e. a reason other than reading or writing) is the cause of the condition.
63.Pp 64.Pp
64.Fn BIO_retry_type 65.Fn BIO_retry_type
65returns a mask of the cause of a retry condition consisting of the values 66returns a mask of the cause of a retry condition consisting of the values
@@ -82,7 +83,7 @@ depends on the type of BIO that resulted in this condition.
82returns the reason for a special condition 83returns the reason for a special condition
83if passed the relevant BIO, for example as returned by 84if passed the relevant BIO, for example as returned by
84.Fn BIO_get_retry_BIO . 85.Fn BIO_get_retry_BIO .
85.Sh NOTES 86.Pp
86If 87If
87.Fn BIO_should_retry 88.Fn BIO_should_retry
88returns false, then the precise "error condition" depends on 89returns false, then the precise "error condition" depends on
@@ -114,7 +115,7 @@ or avoid this situation by setting
114.Dv SSL_MODE_AUTO_RETRY 115.Dv SSL_MODE_AUTO_RETRY
115on the underlying SSL structure. 116on the underlying SSL structure.
116.Pp 117.Pp
117While an application may retry a failed non blocking call immediately, 118While an application may retry a failed non-blocking call immediately,
118this is likely to be very inefficient because the call will fail 119this is likely to be very inefficient because the call will fail
119repeatedly until data can be processed or is available. 120repeatedly until data can be processed or is available.
120An application will normally wait until the necessary condition 121An application will normally wait until the necessary condition
@@ -127,7 +128,7 @@ is true then a call to
127.Xr select 2 128.Xr select 2
128may be made to wait until data is available 129may be made to wait until data is available
129and then retry the BIO operation. 130and then retry the BIO operation.
130By combining the retry conditions of several non blocking BIOs in a single 131By combining the retry conditions of several non-blocking BIOs in a single
131.Xr select 2 132.Xr select 2
132call it is possible to service several BIOs in a single thread, 133call it is possible to service several BIOs in a single thread,
133though the performance may be poor if SSL BIOs are present because 134though the performance may be poor if SSL BIOs are present because
@@ -136,12 +137,12 @@ long delays can occur during the initial handshake process.
136It is possible for a BIO to block indefinitely if the underlying I/O 137It is possible for a BIO to block indefinitely if the underlying I/O
137structure cannot process or return any data. 138structure cannot process or return any data.
138This depends on the behaviour of the platforms I/O functions. 139This depends on the behaviour of the platforms I/O functions.
139This is often not desirable: one solution is to use non blocking I/O 140This is often not desirable: one solution is to use non-blocking I/O
140and use a timeout on the 141and use a timeout on the
141.Xr select 2 142.Xr select 2
142(or equivalent) call. 143(or equivalent) call.
143.Sh BUGS 144.Sh BUGS
144The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O: 145The OpenSSL ASN.1 functions cannot gracefully deal with non-blocking I/O:
145they cannot retry after a partial read or write. 146they cannot retry after a partial read or write.
146This is usually worked around by only passing the relevant data to ASN1 147This is usually worked around by only passing the relevant data to ASN.1
147functions when the entire structure can be read or written. 148functions when the entire structure can be read or written.