Added an explicit yield (OP_SLEEP) to QUIC testing for cooperative threading.

[openssl.git] / doc / man3 / BIO_ctrl.pod

diff --git a/doc/man3/BIO_ctrl.pod b/doc/man3/BIO_ctrl.pod
index b3108f83ef52004ee008158df7b95a8bf4437893..2f9f3978e8f0b49a8392a962cfac24dd466cbdbd 100644 (file)
--- a/doc/man3/BIO_ctrl.pod
+++ b/doc/man3/BIO_ctrl.pod
@@ -6,7 +6,7 @@ BIO_ctrl, BIO_callback_ctrl, BIO_ptr_ctrl, BIO_int_ctrl, BIO_reset,
 BIO_seek, BIO_tell, BIO_flush, BIO_eof, BIO_set_close, BIO_get_close,
 BIO_pending, BIO_wpending, BIO_ctrl_pending, BIO_ctrl_wpending,
 BIO_get_info_callback, BIO_set_info_callback, BIO_info_cb, BIO_get_ktls_send,
-BIO_get_ktls_recv
+BIO_get_ktls_recv, BIO_set_conn_mode, BIO_get_conn_mode, BIO_set_tfo
 - BIO control operations
 
 =head1 SYNOPSIS
@@ -17,7 +17,7 @@ BIO_get_ktls_recv
 
  long BIO_ctrl(BIO *bp, int cmd, long larg, void *parg);
  long BIO_callback_ctrl(BIO *b, int cmd, BIO_info_cb *cb);
- char *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
+ void *BIO_ptr_ctrl(BIO *bp, int cmd, long larg);
  long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
 
  int BIO_reset(BIO *b);
@@ -38,6 +38,11 @@ BIO_get_ktls_recv
  int BIO_get_ktls_send(BIO *b);
  int BIO_get_ktls_recv(BIO *b);
 
+ int BIO_set_conn_mode(BIO *b, int mode);
+ int BIO_get_conn_mode(BIO *b);
+
+ int BIO_set_tfo(BIO *b, int onoff);
+
 =head1 DESCRIPTION
 
 BIO_ctrl(), BIO_callback_ctrl(), BIO_ptr_ctrl() and BIO_int_ctrl()
@@ -81,31 +86,54 @@ sending. Otherwise, it returns zero.
 BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for
 receiving. Otherwise, it returns zero.
 
+BIO_get_conn_mode() returns the BIO connection mode. BIO_set_conn_mode() sets
+the BIO connection mode.
+
+BIO_set_tfo() disables TCP Fast Open when B<onoff> is 0, and enables TCP Fast
+Open when B<onoff> is nonzero. Setting the value to 1 is equivalent to setting
+B<BIO_SOCK_TFO> in BIO_set_conn_mode().
+
 =head1 RETURN VALUES
 
-BIO_reset() normally returns 1 for success and 0 or -1 for failure. File
+BIO_reset() normally returns 1 for success and <=0 for failure. File
 BIOs are an exception, they return 0 for success and -1 for failure.
 
 BIO_seek() and BIO_tell() both return the current file position on success
 and -1 for failure, except file BIOs which for BIO_seek() always return 0
 for success and -1 for failure.
 
-BIO_flush() returns 1 for success and 0 or -1 for failure.
+BIO_flush() returns 1 for success and <=0 for failure.
 
-BIO_eof() returns 1 if EOF has been reached, 0 if not, or -1 for failure.
+BIO_eof() returns 1 if EOF has been reached, 0 if not, or negative values for failure.
 
-BIO_set_close() always returns 1.
+BIO_set_close() returns 1 on success or <=0 for failure.
 
-BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE.
+BIO_get_close() returns the close flag value: BIO_CLOSE or BIO_NOCLOSE. It also
+returns other negative values if an error occurs.
 
 BIO_pending(), BIO_ctrl_pending(), BIO_wpending() and BIO_ctrl_wpending()
-return the amount of pending data.
+return the amount of pending data. BIO_pending() and BIO_wpending() return
+negative value or 0 on error. BIO_ctrl_pending() and BIO_ctrl_wpending() return
+0 on error.
 
 BIO_get_ktls_send() returns 1 if the BIO is using the Kernel TLS data-path for
 sending. Otherwise, it returns zero.
 BIO_get_ktls_recv() returns 1 if the BIO is using the Kernel TLS data-path for
 receiving. Otherwise, it returns zero.
 
+BIO_set_conn_mode() returns 1 for success and 0 for failure. BIO_get_conn_mode()
+returns the current connection mode. Which may contain the bitwise-or of the
+following flags:
+
+ BIO_SOCK_REUSEADDR
+ BIO_SOCK_V6_ONLY
+ BIO_SOCK_KEEPALIVE
+ BIO_SOCK_NONBLOCK
+ BIO_SOCK_NODELAY
+ BIO_SOCK_TFO
+
+BIO_set_tfo() returns 1 for success, and 0 for failure.
+
 =head1 NOTES
 
 BIO_flush(), because it can write data may return 0 or -1 indicating
@@ -138,14 +166,20 @@ particular a return value of 0 can be returned if an operation is not
 supported, if an error occurred, if EOF has not been reached and in
 the case of BIO_seek() on a file BIO for a successful operation.
 
+In older versions of OpenSSL the BIO_ctrl_pending() and
+BIO_ctrl_wpending() could return values greater than INT_MAX on error.
+
 =head1 HISTORY
 
-The BIO_get_ktls_send() and BIO_get_ktls_recv() functions were added in
-OpenSSL 3.0.
+The BIO_get_ktls_send() and BIO_get_ktls_recv() macros were added in
+OpenSSL 3.0. They were modified to never return -1 in OpenSSL 3.0.4.
+
+The BIO_get_conn_mode(), BIO_set_conn_mode() and BIO_set_tfo() functions
+were added in OpenSSL 3.2.
 
 =head1 COPYRIGHT
 
-Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2000-2022 The OpenSSL Project Authors. All Rights Reserved.
 
 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