diff options
Diffstat (limited to 'secure/lib/libcrypto/man/BIO_s_bio.3')
| -rw-r--r-- | secure/lib/libcrypto/man/BIO_s_bio.3 | 61 |
1 files changed, 57 insertions, 4 deletions
diff --git a/secure/lib/libcrypto/man/BIO_s_bio.3 b/secure/lib/libcrypto/man/BIO_s_bio.3 index 6c76cd9..49214db 100644 --- a/secure/lib/libcrypto/man/BIO_s_bio.3 +++ b/secure/lib/libcrypto/man/BIO_s_bio.3 @@ -1,5 +1,5 @@ .\" Automatically generated by Pod::Man version 1.15 -.\" Tue Jul 30 09:21:09 2002 +.\" Mon Jan 13 19:27:03 2003 .\" .\" Standard preamble: .\" ====================================================================== @@ -138,7 +138,7 @@ .\" ====================================================================== .\" .IX Title "BIO_s_bio 3" -.TH BIO_s_bio 3 "0.9.6e" "2000-11-12" "OpenSSL" +.TH BIO_s_bio 3 "0.9.7" "2003-01-13" "OpenSSL" .UC .SH "NAME" BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, @@ -223,7 +223,9 @@ If the size is not initialized a default value is used. This is currently \&\fIBIO_new_bio_pair()\fR combines the calls to \fIBIO_new()\fR, \fIBIO_make_bio_pair()\fR and \&\fIBIO_set_write_buf_size()\fR to create a connected pair of BIOs \fBbio1\fR, \fBbio2\fR with write buffer sizes \fBwritebuf1\fR and \fBwritebuf2\fR. If either size is -zero then the default size is used. +zero then the default size is used. \fIBIO_new_bio_pair()\fR does not check whether +\&\fBbio1\fR or \fBbio2\fR do point to some other \s-1BIO\s0, the values are overwritten, +\&\fIBIO_free()\fR is not called. .PP \&\fIBIO_get_write_guarantee()\fR and \fIBIO_ctrl_get_write_guarantee()\fR return the maximum length of data that can be currently written to the \s-1BIO\s0. Writes larger than this @@ -263,9 +265,60 @@ buffer. \fIBIO_read()\fR will initially fail and \fIBIO_should_read()\fR will be the application then waits for data to be available on the underlying transport before flushing the write buffer it will never succeed because the request was never sent! +.SH "RETURN VALUES" +.IX Header "RETURN VALUES" +\&\fIBIO_new_bio_pair()\fR returns 1 on success, with the new BIOs available in +\&\fBbio1\fR and \fBbio2\fR, or 0 on failure, with \s-1NULL\s0 pointers stored into the +locations for \fBbio1\fR and \fBbio2\fR. Check the error stack for more information. +.PP +[\s-1XXXXX:\s0 More return values need to be added here] .SH "EXAMPLE" .IX Header "EXAMPLE" -\&\s-1TBA\s0 +The \s-1BIO\s0 pair can be used to have full control over the network access of an +application. The application can call \fIselect()\fR on the socket as required +without having to go through the SSL-interface. +.PP +.Vb 6 +\& BIO *internal_bio, *network_bio; +\& ... +\& BIO_new_bio_pair(internal_bio, 0, network_bio, 0); +\& SSL_set_bio(ssl, internal_bio, internal_bio); +\& SSL_operations(); +\& ... +.Ve +.Vb 9 +\& application | TLS-engine +\& | | +\& +----------> SSL_operations() +\& | /\e || +\& | || \e/ +\& | BIO-pair (internal_bio) +\& +----------< BIO-pair (network_bio) +\& | | +\& socket | +.Ve +.Vb 4 +\& ... +\& SSL_free(ssl); /* implicitly frees internal_bio */ +\& BIO_free(network_bio); +\& ... +.Ve +As the \s-1BIO\s0 pair will only buffer the data and never directly access the +connection, it behaves non-blocking and will return as soon as the write +buffer is full or the read buffer is drained. Then the application has to +flush the write buffer and/or fill the read buffer. +.PP +Use the \fIBIO_ctrl_pending()\fR, to find out whether data is buffered in the \s-1BIO\s0 +and must be transfered to the network. Use \fIBIO_ctrl_get_read_request()\fR to +find out, how many bytes must be written into the buffer before the +\&\fISSL_operation()\fR can successfully be continued. +.SH "WARNING" +.IX Header "WARNING" +As the data is buffered, \fISSL_operation()\fR may return with a \s-1ERROR_SSL_WANT_READ\s0 +condition, but there is still data in the write buffer. An application must +not rely on the error value of \fISSL_operation()\fR but must assure that the +write buffer is always flushed first. Otherwise a deadlock may occur as +the peer might be waiting for the data before being able to continue. .SH "SEE ALSO" .IX Header "SEE ALSO" SSL_set_bio(3), ssl(3), bio(3), |
