upd: openssl to 1.1.0

[cassiopeia.git] / lib / openssl / doc / crypto / BIO_s_bio.pod

diff --git a/lib/openssl/doc/crypto/BIO_s_bio.pod b/lib/openssl/doc/crypto/BIO_s_bio.pod
index 8d0a55a025c73f49a49d5d29afec0f43056b2793..cb46546e2139fc4bafc5ea1f9313b1b948e63da5 100644 (file)
--- a/lib/openssl/doc/crypto/BIO_s_bio.pod
+++ b/lib/openssl/doc/crypto/BIO_s_bio.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr, 
+BIO_s_bio, BIO_make_bio_pair, BIO_destroy_bio_pair, BIO_shutdown_wr,
 BIO_set_write_buf_size, BIO_get_write_buf_size, BIO_new_bio_pair,
 BIO_get_write_guarantee, BIO_ctrl_get_write_guarantee, BIO_get_read_request,
 BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
@@ -11,24 +11,22 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
 
  #include <openssl/bio.h>
 
- BIO_METHOD *BIO_s_bio(void);
+ const BIO_METHOD *BIO_s_bio(void);
 
- #define BIO_make_bio_pair(b1,b2)   (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2)
- #define BIO_destroy_bio_pair(b)    (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL)
+ int BIO_make_bio_pair(BIO *b1, BIO *b2);
+ int BIO_destroy_bio_pair(BIO *b);
+ int BIO_shutdown_wr(BIO *b);
 
- #define BIO_shutdown_wr(b) (int)BIO_ctrl(b, BIO_C_SHUTDOWN_WR, 0, NULL)
 
- #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL)
- #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL)
+ int BIO_set_write_buf_size(BIO *b, long size);
+ size_t BIO_get_write_buf_size(BIO *b, long size);
 
  int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2);
 
- #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL)
+ int BIO_get_write_guarantee(BIO *b);
  size_t BIO_ctrl_get_write_guarantee(BIO *b);
-
- #define BIO_get_read_request(b)    (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL)
+ int BIO_get_read_request(BIO *b);
  size_t BIO_ctrl_get_read_request(BIO *b);
-
  int BIO_ctrl_reset_read_request(BIO *b);
 
 =head1 DESCRIPTION
@@ -65,7 +63,7 @@ up any half of the pair will automatically destroy the association.
 BIO_shutdown_wr() is used to close down a BIO B<b>. After this call no further
 writes on BIO B<b> are allowed (they will return an error). Reads on the other
 half of the pair will return any pending data or EOF when all pending data has
-been read. 
+been read.
 
 BIO_set_write_buf_size() sets the write buffer size of BIO B<b> to B<size>.
 If the size is not initialized a default value is used. This is currently
@@ -120,6 +118,14 @@ 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!
 
+BIO_eof() is true if no data is in the peer BIO and the peer BIO has been
+shutdown.
+
+BIO_make_bio_pair(), BIO_destroy_bio_pair(), BIO_shutdown_wr(),
+BIO_set_write_buf_size(), BIO_get_write_buf_size(),
+BIO_get_write_guarantee(), and BIO_get_read_request() are implemented
+as macros.
+
 =head1 RETURN VALUES
 
 BIO_new_bio_pair() returns 1 on success, with the new BIOs available in
@@ -136,9 +142,9 @@ without having to go through the SSL-interface.
 
  BIO *internal_bio, *network_bio;
  ...
- BIO_new_bio_pair(internal_bio, 0, network_bio, 0);
+ BIO_new_bio_pair(&internal_bio, 0, &network_bio, 0);
  SSL_set_bio(ssl, internal_bio, internal_bio);
- SSL_operations();
+ SSL_operations(); //e.g SSL_read and SSL_write
  ...
 
  application |   TLS-engine
@@ -147,12 +153,16 @@ without having to go through the SSL-interface.
              |     /\    ||
              |     ||    \/
              |   BIO-pair (internal_bio)
-    +----------< BIO-pair (network_bio)
+             |   BIO-pair (network_bio)
+             |     ||     /\
+             |     \/     ||
+    +-----------< BIO_operations()
     |        |
-  socket     |
+    |        |
+   socket
 
   ...
-  SSL_free(ssl);               /* implicitly frees internal_bio */
+  SSL_free(ssl);                /* implicitly frees internal_bio */
   BIO_free(network_bio);
   ...
 
@@ -162,13 +172,13 @@ buffer is full or the read buffer is drained. Then the application has to
 flush the write buffer and/or fill the read buffer.
 
 Use the BIO_ctrl_pending(), to find out whether data is buffered in the BIO
-and must be transfered to the network. Use BIO_ctrl_get_read_request() to
+and must be transferred to the network. Use BIO_ctrl_get_read_request() to
 find out, how many bytes must be written into the buffer before the
 SSL_operation() can successfully be continued.
 
 =head1 WARNING
 
-As the data is buffered, SSL_operation() may return with a ERROR_SSL_WANT_READ
+As the data is buffered, SSL_operation() may return with an ERROR_SSL_WANT_READ
 condition, but there is still data in the write buffer. An application must
 not rely on the error value of SSL_operation() but must assure that the
 write buffer is always flushed first. Otherwise a deadlock may occur as
@@ -176,7 +186,16 @@ the peer might be waiting for the data before being able to continue.
 
 =head1 SEE ALSO
 
-L<SSL_set_bio(3)|SSL_set_bio(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
-L<BIO_should_retry(3)|BIO_should_retry(3)>, L<BIO_read(3)|BIO_read(3)>
+L<SSL_set_bio(3)>, L<ssl(3)>, L<bio(3)>,
+L<BIO_should_retry(3)>, L<BIO_read(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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
+L<https://www.openssl.org/source/license.html>.
 
 =cut