173 lines
7.6 KiB
HTML
173 lines
7.6 KiB
HTML
|
<?xml version="1.0" ?>
|
||
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
|
<head>
|
||
|
<title>BIO_should_retry</title>
|
||
|
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
|
||
|
<link rev="made" href="mailto:root@localhost" />
|
||
|
</head>
|
||
|
|
||
|
<body style="background-color: white">
|
||
|
|
||
|
|
||
|
<!-- INDEX BEGIN -->
|
||
|
<div name="index">
|
||
|
<p><a name="__index__"></a></p>
|
||
|
|
||
|
<ul>
|
||
|
|
||
|
<li><a href="#name">NAME</a></li>
|
||
|
<li><a href="#synopsis">SYNOPSIS</a></li>
|
||
|
<li><a href="#description">DESCRIPTION</a></li>
|
||
|
<li><a href="#notes">NOTES</a></li>
|
||
|
<li><a href="#bugs">BUGS</a></li>
|
||
|
<li><a href="#return_values">RETURN VALUES</a></li>
|
||
|
<li><a href="#see_also">SEE ALSO</a></li>
|
||
|
<li><a href="#history">HISTORY</a></li>
|
||
|
<li><a href="#copyright">COPYRIGHT</a></li>
|
||
|
</ul>
|
||
|
|
||
|
<hr name="index" />
|
||
|
</div>
|
||
|
<!-- INDEX END -->
|
||
|
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="name">NAME</a></h1>
|
||
|
<p>BIO_should_read, BIO_should_write,
|
||
|
BIO_should_io_special, BIO_retry_type, BIO_should_retry,
|
||
|
BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
|
||
|
functions</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="synopsis">SYNOPSIS</a></h1>
|
||
|
<pre>
|
||
|
#include <openssl/bio.h></pre>
|
||
|
<pre>
|
||
|
int BIO_should_read(BIO *b);
|
||
|
int BIO_should_write(BIO *b);
|
||
|
int BIO_should_io_special(iBIO *b);
|
||
|
int BIO_retry_type(BIO *b);
|
||
|
int BIO_should_retry(BIO *b);</pre>
|
||
|
<pre>
|
||
|
BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
|
||
|
int BIO_get_retry_reason(BIO *bio);
|
||
|
void BIO_set_retry_reason(BIO *bio, int reason);</pre>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="description">DESCRIPTION</a></h1>
|
||
|
<p>These functions determine why a BIO is not able to read or write data.
|
||
|
They will typically be called after a failed <code>BIO_read_ex()</code> or <code>BIO_write_ex()</code>
|
||
|
call.</p>
|
||
|
<p><code>BIO_should_retry()</code> is true if the call that produced this condition
|
||
|
should then be retried at a later time.</p>
|
||
|
<p>If <code>BIO_should_retry()</code> is false then the cause is an error condition.</p>
|
||
|
<p><code>BIO_should_read()</code> is true if the cause of the condition is that the BIO
|
||
|
has insufficient data to return. Check for readability and/or retry the
|
||
|
last operation.</p>
|
||
|
<p><code>BIO_should_write()</code> is true if the cause of the condition is that the BIO
|
||
|
has pending data to write. Check for writability and/or retry the
|
||
|
last operation.</p>
|
||
|
<p><code>BIO_should_io_special()</code> is true if some "special" condition, that is a
|
||
|
reason other than reading or writing is the cause of the condition.</p>
|
||
|
<p><code>BIO_retry_type()</code> returns a mask of the cause of a retry condition
|
||
|
consisting of the values <strong>BIO_FLAGS_READ</strong>, <strong>BIO_FLAGS_WRITE</strong>,
|
||
|
<strong>BIO_FLAGS_IO_SPECIAL</strong> though current BIO types will only set one of
|
||
|
these.</p>
|
||
|
<p><code>BIO_get_retry_BIO()</code> determines the precise reason for the special
|
||
|
condition, it returns the BIO that caused this condition and if
|
||
|
<strong>reason</strong> is not NULL it contains the reason code. The meaning of
|
||
|
the reason code and the action that should be taken depends on
|
||
|
the type of BIO that resulted in this condition.</p>
|
||
|
<p><code>BIO_get_retry_reason()</code> returns the reason for a special condition if
|
||
|
passed the relevant BIO, for example as returned by <code>BIO_get_retry_BIO()</code>.</p>
|
||
|
<p><code>BIO_set_retry_reason()</code> sets the retry reason for a special condition for a given
|
||
|
BIO. This would usually only be called by BIO implementations.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="notes">NOTES</a></h1>
|
||
|
<p><code>BIO_should_read()</code>, <code>BIO_should_write()</code>, <code>BIO_should_io_special()</code>,
|
||
|
<code>BIO_retry_type()</code>, and <code>BIO_should_retry()</code>, are implemented as macros.</p>
|
||
|
<p>If <code>BIO_should_retry()</code> returns false then the precise "error condition"
|
||
|
depends on the BIO type that caused it and the return code of the BIO
|
||
|
operation. For example if a call to <code>BIO_read_ex()</code> on a socket BIO returns
|
||
|
0 and <code>BIO_should_retry()</code> is false then the cause will be that the
|
||
|
connection closed. A similar condition on a file BIO will mean that it
|
||
|
has reached EOF. Some BIO types may place additional information on
|
||
|
the error queue. For more details see the individual BIO type manual
|
||
|
pages.</p>
|
||
|
<p>If the underlying I/O structure is in a blocking mode almost all current
|
||
|
BIO types will not request a retry, because the underlying I/O
|
||
|
calls will not. If the application knows that the BIO type will never
|
||
|
signal a retry then it need not call <code>BIO_should_retry()</code> after a failed
|
||
|
BIO I/O call. This is typically done with file BIOs.</p>
|
||
|
<p>SSL BIOs are the only current exception to this rule: they can request a
|
||
|
retry even if the underlying I/O structure is blocking, if a handshake
|
||
|
occurs during a call to <code>BIO_read()</code>. An application can retry the failed
|
||
|
call immediately or avoid this situation by setting SSL_MODE_AUTO_RETRY
|
||
|
on the underlying SSL structure.</p>
|
||
|
<p>While an application may retry a failed non blocking call immediately
|
||
|
this is likely to be very inefficient because the call will fail
|
||
|
repeatedly until data can be processed or is available. An application
|
||
|
will normally wait until the necessary condition is satisfied. How
|
||
|
this is done depends on the underlying I/O structure.</p>
|
||
|
<p>For example if the cause is ultimately a socket and <code>BIO_should_read()</code>
|
||
|
is true then a call to <code>select()</code> may be made to wait until data is
|
||
|
available and then retry the BIO operation. By combining the retry
|
||
|
conditions of several non blocking BIOs in a single <code>select()</code> call
|
||
|
it is possible to service several BIOs in a single thread, though
|
||
|
the performance may be poor if SSL BIOs are present because long delays
|
||
|
can occur during the initial handshake process.</p>
|
||
|
<p>It is possible for a BIO to block indefinitely if the underlying I/O
|
||
|
structure cannot process or return any data. This depends on the behaviour of
|
||
|
the platforms I/O functions. This is often not desirable: one solution
|
||
|
is to use non blocking I/O and use a timeout on the <code>select()</code> (or
|
||
|
equivalent) call.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="bugs">BUGS</a></h1>
|
||
|
<p>The OpenSSL ASN1 functions cannot gracefully deal with non blocking I/O:
|
||
|
that is they cannot retry after a partial read or write. This is usually
|
||
|
worked around by only passing the relevant data to ASN1 functions when
|
||
|
the entire structure can be read or written.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="return_values">RETURN VALUES</a></h1>
|
||
|
<p><code>BIO_should_read()</code>, <code>BIO_should_write()</code>, <code>BIO_should_io_special()</code>, and
|
||
|
<code>BIO_should_retry()</code> return either 1 or 0 based on the actual conditions
|
||
|
of the <strong>BIO</strong>.</p>
|
||
|
<p><code>BIO_retry_type()</code> returns a flag combination presenting the cause of a retry
|
||
|
condition or false if there is no retry condition.</p>
|
||
|
<p><code>BIO_get_retry_BIO()</code> returns a valid <strong>BIO</strong> structure.</p>
|
||
|
<p><code>BIO_get_retry_reason()</code> returns the reason for a special condition.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="see_also">SEE ALSO</a></h1>
|
||
|
<p><em>bio(7)</em></p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="history">HISTORY</a></h1>
|
||
|
<p>The <code>BIO_get_retry_reason()</code> and <code>BIO_set_retry_reason()</code> functions were added in
|
||
|
OpenSSL 1.1.0.</p>
|
||
|
<p>
|
||
|
</p>
|
||
|
<hr />
|
||
|
<h1><a name="copyright">COPYRIGHT</a></h1>
|
||
|
<p>Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.</p>
|
||
|
<p>Licensed under the Apache License 2.0 (the "License"). You may not use
|
||
|
this file except in compliance with the License. You can obtain a copy
|
||
|
in the file LICENSE in the source distribution or at
|
||
|
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
|
||
|
|
||
|
</body>
|
||
|
|
||
|
</html>
|