2 ''' $RCSfile$$Revision$$Date$
20 .ie \\n(.$>=3 .ne \\$3
36 ''' Set up \*(-- to give an unbreakable dash;
37 ''' string Tr holds user defined translation string.
38 ''' Bell System Logo is used as a dummy character.
44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
48 ''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49 ''' \*(L" and \*(R", except that they are used on ".xx" lines,
50 ''' such as .IP and .SH, which do another additional levels of
51 ''' double-quote interpretation
80 .\" If the F register is turned on, we'll generate
81 .\" index entries out stderr for the following things:
86 .\" X<> Xref (embedded
87 .\" Of course, you have to process the output yourself
88 .\" in some meaninful fashion.
91 .tm Index:\\$1\t\\n%\t"\\$2"
96 .TH BIO_should_retry 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101 .de CQ \" put $1 in typewriter font
107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111 . \" AM - accent mark definitions
113 . \" fudge factors for nroff and troff
122 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
128 . \" simple accents for nroff and troff
141 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146 . ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147 . ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149 . ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
151 . \" troff and (daisy-wheel) nroff accents
152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163 .ds ae a\h'-(\w'a'u*4/10)'e
164 .ds Ae A\h'-(\w'A'u*4/10)'E
165 .ds oe o\h'-(\w'o'u*4/10)'e
166 .ds Oe O\h'-(\w'O'u*4/10)'E
167 . \" corrections for vroff
168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
170 . \" for low resolution devices (crt and lpr)
171 .if \n(.H>23 .if \n(.V>19 \
175 . ds v \h'-1'\o'\(aa\(ga'
191 BIO_should_retry, BIO_should_read, BIO_should_write,
192 BIO_should_io_special, BIO_retry_type, BIO_should_retry,
193 BIO_get_retry_BIO, BIO_get_retry_reason \- BIO retry functions
197 \& #include <openssl/bio.h>
200 \& #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
201 \& #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
202 \& #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
203 \& #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
204 \& #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
207 \& #define BIO_FLAGS_READ 0x01
208 \& #define BIO_FLAGS_WRITE 0x02
209 \& #define BIO_FLAGS_IO_SPECIAL 0x04
210 \& #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
211 \& #define BIO_FLAGS_SHOULD_RETRY 0x08
214 \& BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
215 \& int BIO_get_retry_reason(BIO *bio);
218 These functions determine why a BIO is not able to read or write data.
219 They will typically be called after a failed \fIBIO_read()\fR or \fIBIO_write()\fR
222 \fIBIO_should_retry()\fR is true if the call that produced this condition
223 should then be retried at a later time.
225 If \fIBIO_should_retry()\fR is false then the cause is an error condition.
227 \fIBIO_should_read()\fR is true if the cause of the condition is that a BIO
230 \fIBIO_should_write()\fR is true if the cause of the condition is that a BIO
233 \fIBIO_should_io_special()\fR is true if some \*(L"special\*(R" condition, that is a
234 reason other than reading or writing is the cause of the condition.
236 \fIBIO_get_retry_reason()\fR returns a mask of the cause of a retry condition
237 consisting of the values \fBBIO_FLAGS_READ\fR, \fBBIO_FLAGS_WRITE\fR,
238 \fBBIO_FLAGS_IO_SPECIAL\fR though current BIO types will only set one of
241 \fIBIO_get_retry_BIO()\fR determines the precise reason for the special
242 condition, it returns the BIO that caused this condition and if
243 \fBreason\fR is not NULL it contains the reason code. The meaning of
244 the reason code and the action that should be taken depends on
245 the type of BIO that resulted in this condition.
247 \fIBIO_get_retry_reason()\fR returns the reason for a special condition if
248 passed the relevant BIO, for example as returned by \fIBIO_get_retry_BIO()\fR.
250 If \fIBIO_should_retry()\fR returns false then the precise \*(L"error condition\*(R"
251 depends on the BIO type that caused it and the return code of the BIO
252 operation. For example if a call to \fIBIO_read()\fR on a socket BIO returns
253 0 and \fIBIO_should_retry()\fR is false then the cause will be that the
254 connection closed. A similar condition on a file BIO will mean that it
255 has reached EOF. Some BIO types may place additional information on
256 the error queue. For more details see the individual BIO type manual
259 If the underlying I/O structure is in a blocking mode almost all current
260 BIO types will not request a retry, because the underlying I/O
261 calls will not. If the application knows that the BIO type will never
262 signal a retry then it need not call \fIBIO_should_retry()\fR after a failed
263 BIO I/O call. This is typically done with file BIOs.
265 SSL BIOs are the only current exception to this rule: they can request a
266 retry even if the underlying I/O structure is blocking, if a handshake
267 occurs during a call to \fIBIO_read()\fR. An application can retry the failed
268 call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
269 on the underlying SSL structure.
271 While an application may retry a failed non blocking call immediately
272 this is likely to be very inefficient because the call will fail
273 repeatedly until data can be processed or is available. An application
274 will normally wait until the necessary condition is satisfied. How
275 this is done depends on the underlying I/O structure.
277 For example if the cause is ultimately a socket and \fIBIO_should_read()\fR
278 is true then a call to \fIselect()\fR may be made to wait until data is
279 available and then retry the BIO operation. By combining the retry
280 conditions of several non blocking BIOs in a single \fIselect()\fR call
281 it is possible to service several BIOs in a single thread, though
282 the performance may be poor if SSL BIOs are present because long delays
283 can occur during the initial handshake process.
285 It is possible for a BIO to block indefinitely if the underlying I/O
286 structure cannot process or return any data. This depends on the behaviour of
287 the platforms I/O functions. This is often not desirable: one solution
288 is to use non blocking I/O and use a timeout on the \fIselect()\fR (or
291 The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
292 that is they cannot retry after a partial read or write. This is usually
293 worked around by only passing the relevant data to ASN1 functions when
294 the entire structure can be read or written.
299 .IX Title "BIO_should_retry 3"
300 .IX Name "BIO_should_retry, BIO_should_read, BIO_should_write,
301 BIO_should_io_special, BIO_retry_type, BIO_should_retry,
302 BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions"
306 .IX Header "SYNOPSIS"
308 .IX Header "DESCRIPTION"
314 .IX Header "SEE ALSO"