secure/lib/libcrypto/man/BIO_should_retry.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  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 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  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' '
  62 'br\}
  63 .el\{\
  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
  79 'br\}
  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"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH BIO_should_retry 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 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
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 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'
 150 .\}
 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 \
 172 \{\
 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
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 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
 194 .SH "SYNOPSIS"
 195 .PP
 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"
 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
 220 call.
 221 .PP
 222 \fIBIO_should_retry()\fR is true if the call that produced this condition
 223 should then be retried at a later time.
 224 .PP
 225 If \fIBIO_should_retry()\fR is false then the cause is an error condition.
 226 .PP
 227 \fIBIO_should_read()\fR is true if the cause of the condition is that a BIO
 228 needs to read data.
 229 .PP
 230 \fIBIO_should_write()\fR is true if the cause of the condition is that a BIO
 231 needs to read data.
 232 .PP
 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.
 235 .PP
 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
 239 these.
 240 .PP
 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.
 246 .PP
 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.
 249 .SH "NOTES"
 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
 257 pages.
 258 .PP
 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.
 264 .PP
 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.
 270 .PP
 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.
 276 .PP
 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.
 284 .PP
 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
 289 equivalent) call.
 290 .SH "BUGS"
 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.
 295 .SH "SEE ALSO"
 296 TBA
 297
 298 .rn }` ''
 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"
 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
 314 .IX Header "SEE ALSO"
 315