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