Remove -WX option from debug-VC-WIN32

[openssl.git] / doc / crypto / BIO_read.pod

diff --git a/doc/crypto/BIO_read.pod b/doc/crypto/BIO_read.pod
index 16787e386e224c5c66e3a6b75472dc94d85588d3..b34528104ddf248813b68c666111f0316986aefc 100644 (file)
--- a/doc/crypto/BIO_read.pod
+++ b/doc/crypto/BIO_read.pod
@@ -2,16 +2,16 @@
 
 =head1 NAME
 
-       BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
+BIO_read, BIO_write, BIO_gets, BIO_puts - BIO I/O functions
 
 =head1 SYNOPSIS
 
  #include <openssl/bio.h>
 
-int    BIO_read(BIO *b, void *buf, int len);
-int    BIO_gets(BIO *b,char *buf, int size);
-int    BIO_write(BIO *b, const void *buf, int len);
-int    BIO_puts(BIO *b,const char *buf);
+ int   BIO_read(BIO *b, void *buf, int len);
+ int   BIO_gets(BIO *b,char *buf, int size);
+ int   BIO_write(BIO *b, const void *buf, int len);
+ int   BIO_puts(BIO *b,const char *buf);
 
 =head1 DESCRIPTION
 
@@ -32,16 +32,28 @@ BIO_puts() attempts to write a null terminated string B<buf> to BIO B<b>
 
 All these functions return either the amount of data successfully read or
 written (if the return value is positive) or that no data was successfully
-read or written (if the result is zero or negative).
+read or written if the result is 0 or -1. If the return value is -2 then
+the operation is not implemented in the specific BIO type.
 
 =head1 NOTES
 
-A negative or zero return is not necessarily an indication of an error. In
-particular when the source/sink is non-blocking or of a certain type (for
-example an SSL BIO can retry even if the underlying connection is blocking)
+A 0 or -1 return is not necessarily an indication of an error. In
+particular when the source/sink is non-blocking or of a certain type
 it may merely be an indication that no data is currently available and that
-the application should retry the operation later. L<BIO_should_retry(3)|BIO_should_retry(3)>
-can be called to determine the precise cause.
+the application should retry the operation later.
+
+One technique sometimes used with blocking sockets is to use a system call
+(such as select(), poll() or equivalent) to determine when data is available
+and then call read() to read the data. The equivalent with BIOs (that is call
+select() on the underlying I/O structure and then call BIO_read() to
+read the data) should B<not> be used because a single call to BIO_read()
+can cause several reads (and writes in the case of SSL BIOs) on the underlying
+I/O structure and may block as a result. Instead select() (or equivalent)
+should be combined with non blocking I/O so successive reads will request
+a retry instead of blocking.
+
+See L<BIO_should_retry(3)|BIO_should_retry(3)> for details of how to
+determine the cause of a retry and other I/O issues.
 
 If the BIO_gets() function is not supported by a BIO then it possible to
 work around this by adding a buffering BIO L<BIO_f_buffer(3)|BIO_f_buffer(3)>
@@ -49,4 +61,6 @@ to the chain.
 
 =head1 SEE ALSO
 
+L<BIO_should_retry(3)|BIO_should_retry(3)>
+
 TBA