Deprecate old style BIO callback calls

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

diff --git a/doc/man3/BIO_set_callback.pod b/doc/man3/BIO_set_callback.pod
index 975fef78d23f08e71933523f5e79897a9ad996b4..e3b86c095c232f34d1dbbec93e70fc4ba74a5154 100644 (file)
--- a/doc/man3/BIO_set_callback.pod
+++ b/doc/man3/BIO_set_callback.pod
@@ -4,7 +4,7 @@
 
 BIO_set_callback_ex, BIO_get_callback_ex, BIO_set_callback, BIO_get_callback,
 BIO_set_callback_arg, BIO_get_callback_arg, BIO_debug_callback,
-BIO_callback_fn_ex, BIO_callback_fn
+BIO_debug_callback_ex, BIO_callback_fn_ex, BIO_callback_fn
 - BIO callback functions
 
 =head1 SYNOPSIS
@@ -14,17 +14,24 @@ BIO_callback_fn_ex, BIO_callback_fn
  typedef long (*BIO_callback_fn_ex)(BIO *b, int oper, const char *argp,
                                     size_t len, int argi,
                                     long argl, int ret, size_t *processed);
- typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
-                                 long argl, long ret);
 
  void BIO_set_callback_ex(BIO *b, BIO_callback_fn_ex callback);
  BIO_callback_fn_ex BIO_get_callback_ex(const BIO *b);
 
- void BIO_set_callback(BIO *b, BIO_callback_fn cb);
- BIO_callback_fn BIO_get_callback(BIO *b);
  void BIO_set_callback_arg(BIO *b, char *arg);
  char *BIO_get_callback_arg(const BIO *b);
 
+ long BIO_debug_callback_ex(BIO *bio, int oper, const char *argp, size_t len,
+                            int argi, long argl, int ret, size_t *processed);
+
+ Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+ OPENSSL_API_COMPAT with a suitable version value, see
+ openssl_user_macros(7):
+
+ typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
+                                 long argl, long ret);
+ void BIO_set_callback(BIO *b, BIO_callback_fn cb);
+ BIO_callback_fn BIO_get_callback(BIO *b);
  long BIO_debug_callback(BIO *bio, int cmd, const char *argp, int argi,
                          long argl, long ret);
 
@@ -43,10 +50,12 @@ called in preference to any set by BIO_set_callback().
 BIO_set_callback_arg() and BIO_get_callback_arg() are macros which can be
 used to set and retrieve an argument for use in the callback.
 
-BIO_debug_callback() is a standard debugging callback which prints
+BIO_debug_callback_ex() is a standard debugging callback which prints
 out information relating to each BIO operation. If the callback
 argument is set it is interpreted as a BIO to send the information
-to, otherwise stderr is used.
+to, otherwise stderr is used. The BIO_debug_callback() function is the
+deprecated version of the same callback for use with the old callback
+format BIO_set_callback() function.
 
 BIO_callback_fn_ex is the type of the callback function and BIO_callback_fn
 is the type of the old format callback function. The meaning of each argument
@@ -225,9 +234,16 @@ operations.
 
 =head1 EXAMPLES
 
-The BIO_debug_callback() function is a good example, its source is
+The BIO_debug_callback_ex() function is an example, its source is
 in crypto/bio/bio_cb.c
 
+=head1 HISTORY
+
+The BIO_debug_callback_ex() function was added in OpenSSL 3.0.
+
+BIO_set_callback(), BIO_get_callback(), and BIO_debug_callback() were
+deprecated in OpenSSL 3.0. Use the non-deprecated _ex functions instead.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.