Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / BIO_should_retry.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
aac4ff6f
PA
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
8b0cefbb
JR
68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69.\" Fear. Run. Save yourself. No user-serviceable parts.
70. \" fudge factors for nroff and troff
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
95. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
103.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110.ds ae a\h'-(\w'a'u*4/10)'e
111.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 112. \" corrections for vroff
984263bc
MD
113.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
118. ds : e
119. ds 8 ss
120. ds o a
121. ds d- d\h'-1'\(ga
122. ds D- D\h'-1'\(hy
123. ds th \o'bp'
124. ds Th \o'LP'
125. ds ae ae
126. ds Ae AE
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "BIO_should_retry 3"
aac4ff6f 132.TH BIO_should_retry 3 "2008-09-06" "0.9.8h" "OpenSSL"
984263bc
MD
133.SH "NAME"
134BIO_should_retry, BIO_should_read, BIO_should_write,
135BIO_should_io_special, BIO_retry_type, BIO_should_retry,
74dab6c2 136BIO_get_retry_BIO, BIO_get_retry_reason \- BIO retry functions
984263bc 137.SH "SYNOPSIS"
8b0cefbb 138.IX Header "SYNOPSIS"
984263bc
MD
139.Vb 1
140\& #include <openssl/bio.h>
aac4ff6f
PA
141.Ve
142.PP
143.Vb 5
144\& #define BIO_should_read(a) ((a)->flags & BIO_FLAGS_READ)
145\& #define BIO_should_write(a) ((a)->flags & BIO_FLAGS_WRITE)
146\& #define BIO_should_io_special(a) ((a)->flags & BIO_FLAGS_IO_SPECIAL)
147\& #define BIO_retry_type(a) ((a)->flags & BIO_FLAGS_RWS)
148\& #define BIO_should_retry(a) ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
149.Ve
150.PP
151.Vb 5
984263bc
MD
152\& #define BIO_FLAGS_READ 0x01
153\& #define BIO_FLAGS_WRITE 0x02
154\& #define BIO_FLAGS_IO_SPECIAL 0x04
155\& #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
156\& #define BIO_FLAGS_SHOULD_RETRY 0x08
aac4ff6f
PA
157.Ve
158.PP
159.Vb 2
984263bc
MD
160\& BIO * BIO_get_retry_BIO(BIO *bio, int *reason);
161\& int BIO_get_retry_reason(BIO *bio);
162.Ve
163.SH "DESCRIPTION"
8b0cefbb
JR
164.IX Header "DESCRIPTION"
165These functions determine why a \s-1BIO\s0 is not able to read or write data.
984263bc
MD
166They will typically be called after a failed \fIBIO_read()\fR or \fIBIO_write()\fR
167call.
168.PP
8b0cefbb 169\&\fIBIO_should_retry()\fR is true if the call that produced this condition
984263bc
MD
170should then be retried at a later time.
171.PP
172If \fIBIO_should_retry()\fR is false then the cause is an error condition.
173.PP
8b0cefbb 174\&\fIBIO_should_read()\fR is true if the cause of the condition is that a \s-1BIO\s0
984263bc
MD
175needs to read data.
176.PP
8b0cefbb 177\&\fIBIO_should_write()\fR is true if the cause of the condition is that a \s-1BIO\s0
984263bc
MD
178needs to read data.
179.PP
8b0cefbb 180\&\fIBIO_should_io_special()\fR is true if some \*(L"special\*(R" condition, that is a
984263bc
MD
181reason other than reading or writing is the cause of the condition.
182.PP
8b0cefbb
JR
183\&\fIBIO_get_retry_reason()\fR returns a mask of the cause of a retry condition
184consisting of the values \fB\s-1BIO_FLAGS_READ\s0\fR, \fB\s-1BIO_FLAGS_WRITE\s0\fR,
185\&\fB\s-1BIO_FLAGS_IO_SPECIAL\s0\fR though current \s-1BIO\s0 types will only set one of
984263bc
MD
186these.
187.PP
8b0cefbb
JR
188\&\fIBIO_get_retry_BIO()\fR determines the precise reason for the special
189condition, it returns the \s-1BIO\s0 that caused this condition and if
190\&\fBreason\fR is not \s-1NULL\s0 it contains the reason code. The meaning of
984263bc 191the reason code and the action that should be taken depends on
8b0cefbb 192the type of \s-1BIO\s0 that resulted in this condition.
984263bc 193.PP
8b0cefbb
JR
194\&\fIBIO_get_retry_reason()\fR returns the reason for a special condition if
195passed the relevant \s-1BIO\s0, for example as returned by \fIBIO_get_retry_BIO()\fR.
984263bc 196.SH "NOTES"
8b0cefbb 197.IX Header "NOTES"
984263bc 198If \fIBIO_should_retry()\fR returns false then the precise \*(L"error condition\*(R"
8b0cefbb
JR
199depends on the \s-1BIO\s0 type that caused it and the return code of the \s-1BIO\s0
200operation. For example if a call to \fIBIO_read()\fR on a socket \s-1BIO\s0 returns
984263bc 2010 and \fIBIO_should_retry()\fR is false then the cause will be that the
8b0cefbb
JR
202connection closed. A similar condition on a file \s-1BIO\s0 will mean that it
203has reached \s-1EOF\s0. Some \s-1BIO\s0 types may place additional information on
204the error queue. For more details see the individual \s-1BIO\s0 type manual
984263bc
MD
205pages.
206.PP
207If the underlying I/O structure is in a blocking mode almost all current
8b0cefbb
JR
208\&\s-1BIO\s0 types will not request a retry, because the underlying I/O
209calls will not. If the application knows that the \s-1BIO\s0 type will never
984263bc 210signal a retry then it need not call \fIBIO_should_retry()\fR after a failed
8b0cefbb 211\&\s-1BIO\s0 I/O call. This is typically done with file BIOs.
984263bc 212.PP
8b0cefbb 213\&\s-1SSL\s0 BIOs are the only current exception to this rule: they can request a
984263bc
MD
214retry even if the underlying I/O structure is blocking, if a handshake
215occurs during a call to \fIBIO_read()\fR. An application can retry the failed
8b0cefbb
JR
216call immediately or avoid this situation by setting \s-1SSL_MODE_AUTO_RETRY\s0
217on the underlying \s-1SSL\s0 structure.
984263bc
MD
218.PP
219While an application may retry a failed non blocking call immediately
220this is likely to be very inefficient because the call will fail
221repeatedly until data can be processed or is available. An application
222will normally wait until the necessary condition is satisfied. How
223this is done depends on the underlying I/O structure.
224.PP
225For example if the cause is ultimately a socket and \fIBIO_should_read()\fR
226is true then a call to \fIselect()\fR may be made to wait until data is
8b0cefbb 227available and then retry the \s-1BIO\s0 operation. By combining the retry
984263bc
MD
228conditions of several non blocking BIOs in a single \fIselect()\fR call
229it is possible to service several BIOs in a single thread, though
8b0cefbb 230the performance may be poor if \s-1SSL\s0 BIOs are present because long delays
aac4ff6f 231can occur during the initial handshake process.
984263bc 232.PP
8b0cefbb 233It is possible for a \s-1BIO\s0 to block indefinitely if the underlying I/O
984263bc
MD
234structure cannot process or return any data. This depends on the behaviour of
235the platforms I/O functions. This is often not desirable: one solution
236is to use non blocking I/O and use a timeout on the \fIselect()\fR (or
237equivalent) call.
238.SH "BUGS"
8b0cefbb
JR
239.IX Header "BUGS"
240The OpenSSL \s-1ASN1\s0 functions cannot gracefully deal with non blocking I/O:
984263bc 241that is they cannot retry after a partial read or write. This is usually
8b0cefbb 242worked around by only passing the relevant data to \s-1ASN1\s0 functions when
984263bc
MD
243the entire structure can be read or written.
244.SH "SEE ALSO"
245.IX Header "SEE ALSO"
8b0cefbb 246\&\s-1TBA\s0