Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_should_retry.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
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.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
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
46.ds L" ""
47.ds R" ""
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
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH BIO_should_retry 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
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
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
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'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
74dab6c2
JR
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'\*(#]
984263bc
MD
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
74dab6c2
JR
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
984263bc
MD
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'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191BIO_should_retry, BIO_should_read, BIO_should_write,
192BIO_should_io_special, BIO_retry_type, BIO_should_retry,
74dab6c2 193BIO_get_retry_BIO, BIO_get_retry_reason \- BIO retry functions
984263bc 194.SH "SYNOPSIS"
74dab6c2 195.PP
984263bc
MD
196.Vb 1
197\& #include <openssl/bio.h>
198.Ve
199.Vb 5
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)
205.Ve
206.Vb 5
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
212.Ve
213.Vb 2
214\& BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
215\& int BIO_get_retry_reason(BIO *bio);
216.Ve
217.SH "DESCRIPTION"
74dab6c2 218These functions determine why a BIO is not able to read or write data.
984263bc
MD
219They will typically be called after a failed \fIBIO_read()\fR or \fIBIO_write()\fR
220call.
221.PP
74dab6c2 222\fIBIO_should_retry()\fR is true if the call that produced this condition
984263bc
MD
223should then be retried at a later time.
224.PP
225If \fIBIO_should_retry()\fR is false then the cause is an error condition.
226.PP
74dab6c2 227\fIBIO_should_read()\fR is true if the cause of the condition is that a BIO
984263bc
MD
228needs to read data.
229.PP
74dab6c2 230\fIBIO_should_write()\fR is true if the cause of the condition is that a BIO
984263bc
MD
231needs to read data.
232.PP
74dab6c2 233\fIBIO_should_io_special()\fR is true if some \*(L"special\*(R" condition, that is a
984263bc
MD
234reason other than reading or writing is the cause of the condition.
235.PP
74dab6c2
JR
236\fIBIO_get_retry_reason()\fR returns a mask of the cause of a retry condition
237consisting 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
984263bc
MD
239these.
240.PP
74dab6c2
JR
241\fIBIO_get_retry_BIO()\fR determines the precise reason for the special
242condition, it returns the BIO that caused this condition and if
243\fBreason\fR is not NULL it contains the reason code. The meaning of
984263bc 244the reason code and the action that should be taken depends on
74dab6c2 245the type of BIO that resulted in this condition.
984263bc 246.PP
74dab6c2
JR
247\fIBIO_get_retry_reason()\fR returns the reason for a special condition if
248passed the relevant BIO, for example as returned by \fIBIO_get_retry_BIO()\fR.
984263bc 249.SH "NOTES"
984263bc 250If \fIBIO_should_retry()\fR returns false then the precise \*(L"error condition\*(R"
74dab6c2
JR
251depends on the BIO type that caused it and the return code of the BIO
252operation. For example if a call to \fIBIO_read()\fR on a socket BIO returns
984263bc 2530 and \fIBIO_should_retry()\fR is false then the cause will be that the
74dab6c2
JR
254connection closed. A similar condition on a file BIO will mean that it
255has reached EOF. Some BIO types may place additional information on
256the error queue. For more details see the individual BIO type manual
984263bc
MD
257pages.
258.PP
259If the underlying I/O structure is in a blocking mode almost all current
74dab6c2
JR
260BIO types will not request a retry, because the underlying I/O
261calls will not. If the application knows that the BIO type will never
984263bc 262signal a retry then it need not call \fIBIO_should_retry()\fR after a failed
74dab6c2 263BIO I/O call. This is typically done with file BIOs.
984263bc 264.PP
74dab6c2 265SSL BIOs are the only current exception to this rule: they can request a
984263bc
MD
266retry even if the underlying I/O structure is blocking, if a handshake
267occurs during a call to \fIBIO_read()\fR. An application can retry the failed
74dab6c2
JR
268call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
269on the underlying SSL structure.
984263bc
MD
270.PP
271While an application may retry a failed non blocking call immediately
272this is likely to be very inefficient because the call will fail
273repeatedly until data can be processed or is available. An application
274will normally wait until the necessary condition is satisfied. How
275this is done depends on the underlying I/O structure.
276.PP
277For example if the cause is ultimately a socket and \fIBIO_should_read()\fR
278is true then a call to \fIselect()\fR may be made to wait until data is
74dab6c2 279available and then retry the BIO operation. By combining the retry
984263bc
MD
280conditions of several non blocking BIOs in a single \fIselect()\fR call
281it is possible to service several BIOs in a single thread, though
74dab6c2 282the performance may be poor if SSL BIOs are present because long delays
984263bc
MD
283can occur during the initial handshake process.
284.PP
74dab6c2 285It is possible for a BIO to block indefinitely if the underlying I/O
984263bc
MD
286structure cannot process or return any data. This depends on the behaviour of
287the platforms I/O functions. This is often not desirable: one solution
288is to use non blocking I/O and use a timeout on the \fIselect()\fR (or
289equivalent) call.
290.SH "BUGS"
74dab6c2 291The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
984263bc 292that is they cannot retry after a partial read or write. This is usually
74dab6c2 293worked around by only passing the relevant data to ASN1 functions when
984263bc
MD
294the entire structure can be read or written.
295.SH "SEE ALSO"
74dab6c2
JR
296TBA
297
298.rn }` ''
299.IX Title "BIO_should_retry 3"
300.IX Name "BIO_should_retry, BIO_should_read, BIO_should_write,
301BIO_should_io_special, BIO_retry_type, BIO_should_retry,
302BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions"
303
304.IX Header "NAME"
305
306.IX Header "SYNOPSIS"
307
308.IX Header "DESCRIPTION"
309
310.IX Header "NOTES"
311
312.IX Header "BUGS"
313
984263bc 314.IX Header "SEE ALSO"
74dab6c2 315