Replace all #define's in pod pages.

Function-like macros are replaced with prototypes and a note
that they are implemented as macros.  Constants are just
referenced in-line in the text.

Tweak BIO_TYPE_... documentation.

Also fix RT4592.

Reviewed-by: Matt Caswell <matt@openssl.org>

38 files changed, 285 insertions, 351 deletions

diff --git a/doc/crypto/ASYNC_start_job.pod b/doc/crypto/ASYNC_start_job.pod
index eb12da8cb9..edec50b573 100644
--- a/doc/crypto/ASYNC_start_job.pod
+++ b/doc/crypto/ASYNC_start_job.pod
@@ -182,8 +182,6 @@ The following example demonstrates how to use most of the core async APIs:
  #include <openssl/async.h>
  #include <openssl/crypto.h>
 
- #define WAIT_SIGNAL_CHAR   'X'
-
  int unique = 0;
 
  void cleanup(ASYNC_WAIT_CTX *ctx, const void *key, OSSL_ASYNC_FD r, void *vw)
@@ -200,7 +198,7 @@ The following example demonstrates how to use most of the core async APIs:
      unsigned char *msg;
      int pipefds[2] = {0, 0};
      OSSL_ASYNC_FD *wptr;
-     char buf = WAIT_SIGNAL_CHAR;
+     char buf = 'X';
 
      currjob = ASYNC_get_current_job();
      if (currjob != NULL) {
diff --git a/doc/crypto/BIO_ctrl.pod b/doc/crypto/BIO_ctrl.pod
index d6d0df1c5a..17dc6ed903 100644
--- a/doc/crypto/BIO_ctrl.pod
+++ b/doc/crypto/BIO_ctrl.pod
@@ -11,27 +11,27 @@ BIO_get_info_callback, BIO_set_info_callback - BIO control operations
 
  #include <openssl/bio.h>
 
- long BIO_ctrl(BIO *bp,int cmd,long larg,void *parg);
- long BIO_callback_ctrl(BIO *b, int cmd, void (*fp)(struct bio_st *, int, const char *, int, long, long));
- char * BIO_ptr_ctrl(BIO *bp,int cmd,long larg);
- long BIO_int_ctrl(BIO *bp,int cmd,long larg,int iarg);
+ typedef void (*bio_info_cb)(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
+
+ 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);
+ long BIO_int_ctrl(BIO *bp, int cmd, long larg, int iarg);
 
  int BIO_reset(BIO *b);
  int BIO_seek(BIO *b, int ofs);
  int BIO_tell(BIO *b);
  int BIO_flush(BIO *b);
  int BIO_eof(BIO *b);
- int BIO_set_close(BIO *b,long flag);
+ int BIO_set_close(BIO *b, long flag);
  int BIO_get_close(BIO *b);
  int BIO_pending(BIO *b);
  int BIO_wpending(BIO *b);
  size_t BIO_ctrl_pending(BIO *b);
  size_t BIO_ctrl_wpending(BIO *b);
 
- int BIO_get_info_callback(BIO *b,bio_info_cb **cbp);
- int BIO_set_info_callback(BIO *b,bio_info_cb *cb);
-
- typedef void bio_info_cb(BIO *b, int oper, const char *ptr, int arg1, long arg2, long arg3);
+ int BIO_get_info_callback(BIO *b, bio_info_cb **cbp);
+ int BIO_set_info_callback(BIO *b, bio_info_cb *cb);
 
 =head1 DESCRIPTION
 
diff --git a/doc/crypto/BIO_f_buffer.pod b/doc/crypto/BIO_f_buffer.pod
index 286a39c9ed..3224710942 100644
--- a/doc/crypto/BIO_f_buffer.pod
+++ b/doc/crypto/BIO_f_buffer.pod
@@ -7,19 +7,20 @@ BIO_set_read_buffer_size,
 BIO_set_write_buffer_size,
 BIO_set_buffer_size,
 BIO_set_buffer_read_data,
-BIO_f_buffer - buffering BIO
+BIO_f_buffer
+- buffering BIO
 
 =head1 SYNOPSIS
 
  #include <openssl/bio.h>
 
- const BIO_METHOD * BIO_f_buffer(void);
+ const BIO_METHOD *BIO_f_buffer(void);
 
- #define BIO_get_buffer_num_lines(b)
- #define BIO_set_read_buffer_size(b,size)
- #define BIO_set_write_buffer_size(b,size)
- #define BIO_set_buffer_size(b,size)
- #define BIO_set_buffer_read_data(b,buf,num)
+ long BIO_get_buffer_num_lines(BIO *b);
+ long BIO_set_read_buffer_size(BIO *b, long size);
+ long BIO_set_write_buffer_size(BIO *b, long size);
+ long BIO_set_buffer_size(BIO *b, long size);
+ long BIO_set_buffer_read_data(BIO *b, void *buf, long num);
 
 =head1 DESCRIPTION
 
@@ -46,6 +47,8 @@ is expanded.
 
 =head1 NOTES
 
+These functions, other than BIO_f_buffer(), are implemented as macros.
+
 Buffering BIOs implement BIO_gets() by using BIO_read() operations on the
 next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
 possible to provide BIO_gets() functionality if the following BIOs do not
diff --git a/doc/crypto/BIO_f_ssl.pod b/doc/crypto/BIO_f_ssl.pod
index 4007130150..1890852179 100644
--- a/doc/crypto/BIO_f_ssl.pod
+++ b/doc/crypto/BIO_f_ssl.pod
@@ -18,23 +18,20 @@ BIO_ssl_shutdown - SSL BIO
 
  const BIO_METHOD *BIO_f_ssl(void);
 
- #define BIO_set_ssl(b,ssl,c)   BIO_ctrl(b,BIO_C_SET_SSL,c,(char *)ssl)
- #define BIO_get_ssl(b,sslp)    BIO_ctrl(b,BIO_C_GET_SSL,0,(char *)sslp)
- #define BIO_set_ssl_mode(b,client)     BIO_ctrl(b,BIO_C_SSL_MODE,client,NULL)
- #define BIO_set_ssl_renegotiate_bytes(b,num) \
-        BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_BYTES,num,NULL);
- #define BIO_set_ssl_renegotiate_timeout(b,seconds) \
-        BIO_ctrl(b,BIO_C_SET_SSL_RENEGOTIATE_TIMEOUT,seconds,NULL);
- #define BIO_get_num_renegotiates(b) \
-        BIO_ctrl(b,BIO_C_SET_SSL_NUM_RENEGOTIATES,0,NULL);
-
- BIO *BIO_new_ssl(SSL_CTX *ctx,int client);
+ long BIO_set_ssl(BIO *b,SSL *ssl, long c);
+ long BIO_get_ssl(BIO *b, SSL **sslp);
+ long BIO_set_ssl_mode(BIO *b, long client);
+ long BIO_set_ssl_renegotiate_bytes(BIO *b, long num);
+ long BIO_set_ssl_renegotiate_timeout(BIO *b, long seconds);
+ long BIO_get_num_renegotiates(BIO *b);
+
+ BIO *BIO_new_ssl(SSL_CTX *ctx, int client);
  BIO *BIO_new_ssl_connect(SSL_CTX *ctx);
  BIO *BIO_new_buffer_ssl_connect(SSL_CTX *ctx);
- int BIO_ssl_copy_session_id(BIO *to,BIO *from);
+ int BIO_ssl_copy_session_id(BIO *to, BIO *from);
  void BIO_ssl_shutdown(BIO *bio);
 
- #define BIO_do_handshake(b)    BIO_ctrl(b,BIO_C_DO_STATE_MACHINE,0,NULL)
+ long BIO_do_handshake(BIO *b);
 
 =head1 DESCRIPTION
 
@@ -128,6 +125,10 @@ Applications do not have to call BIO_do_handshake() but may wish
 to do so to separate the handshake process from other I/O
 processing.
 
+BIO_set_ssl(), BIO_get_ssl(), BIO_set_ssl_mode(),
+BIO_set_ssl_renegotiate_bytes(), BIO_set_ssl_renegotiate_timeout(),
+BIO_get_num_renegotiates(), and BIO_do_handshake() are implemented as macros.
+
 =head1 EXAMPLE
 
 This SSL/TLS client example, attempts to retrieve a page from an
diff --git a/doc/crypto/BIO_find_type.pod b/doc/crypto/BIO_find_type.pod
index f03071ad9b..77fe5597fb 100644
--- a/doc/crypto/BIO_find_type.pod
+++ b/doc/crypto/BIO_find_type.pod
@@ -2,58 +2,29 @@
 
 =head1 NAME
 
-BIO_TYPE_NONE, BIO_TYPE_MEM, BIO_TYPE_FILE, BIO_TYPE_FD, BIO_TYPE_SOCKET,
-BIO_TYPE_NULL, BIO_TYPE_SSL, BIO_TYPE_MD, BIO_TYPE_BUFFER, BIO_TYPE_CIPHER,
-BIO_TYPE_BASE64, BIO_TYPE_CONNECT, BIO_TYPE_ACCEPT, BIO_TYPE_PROXY_CLIENT,
-BIO_TYPE_PROXY_SERVER, BIO_TYPE_NBIO_TEST, BIO_TYPE_NULL_FILTER,
-BIO_TYPE_BER, BIO_TYPE_BIO, BIO_TYPE_DESCRIPTOR, BIO_TYPE_FILTER,
-BIO_TYPE_SOURCE_SINK,
 BIO_find_type, BIO_next, BIO_method_type - BIO chain traversal
 
 =head1 SYNOPSIS
 
  #include <openssl/bio.h>
 
- BIO *  BIO_find_type(BIO *b,int bio_type);
- BIO *  BIO_next(BIO *b);
-
- #define BIO_method_type(b)             ((b)->method->type)
-
- #define BIO_TYPE_NONE          0
- #define BIO_TYPE_MEM           (1|0x0400)
- #define BIO_TYPE_FILE          (2|0x0400)
-
- #define BIO_TYPE_FD            (4|0x0400|0x0100)
- #define BIO_TYPE_SOCKET                (5|0x0400|0x0100)
- #define BIO_TYPE_NULL          (6|0x0400)
- #define BIO_TYPE_SSL           (7|0x0200)
- #define BIO_TYPE_MD            (8|0x0200)
- #define BIO_TYPE_BUFFER                (9|0x0200)
- #define BIO_TYPE_CIPHER                (10|0x0200)
- #define BIO_TYPE_BASE64                (11|0x0200)
- #define BIO_TYPE_CONNECT       (12|0x0400|0x0100)
- #define BIO_TYPE_ACCEPT                (13|0x0400|0x0100)
- #define BIO_TYPE_PROXY_CLIENT  (14|0x0200)
- #define BIO_TYPE_PROXY_SERVER  (15|0x0200)
- #define BIO_TYPE_NBIO_TEST     (16|0x0200)
- #define BIO_TYPE_NULL_FILTER   (17|0x0200)
- #define BIO_TYPE_BER           (18|0x0200)
- #define BIO_TYPE_BIO           (19|0x0400)
-
- #define BIO_TYPE_DESCRIPTOR    0x0100
- #define BIO_TYPE_FILTER                0x0200
- #define BIO_TYPE_SOURCE_SINK   0x0400
+ BIO *BIO_find_type(BIO *b,int bio_type);
+ BIO *BIO_next(BIO *b);
+ int BIO_method_type(const BIO *b);
 
 =head1 DESCRIPTION
 
 The BIO_find_type() searches for a BIO of a given type in a chain, starting
-at BIO B<b>. If B<type> is a specific type (such as BIO_TYPE_MEM) then a search
+at BIO B<b>. If B<type> is a specific type (such as B<BIO_TYPE_MEM>) then a search
 is made for a BIO of that type. If B<type> is a general type (such as
 B<BIO_TYPE_SOURCE_SINK>) then the next matching BIO of the given general type is
 searched for. BIO_find_type() returns the next matching BIO or NULL if none is
 found.
 
-Note: not all the B<BIO_TYPE_*> types above have corresponding BIO implementations.
+The following general types are defined:
+B<BIO_TYPE_DESCRIPTOR>, B<BIO_TYPE_FILTER>, and B<BIO_TYPE_SOURCE_SINK>.
+
+For a list of the defined types, see the B<openssl/bio.h> header file.
 
 BIO_next() returns the next BIO in a chain. It can be used to traverse all BIOs
 in a chain or used in conjunction with BIO_find_type() to find all BIOs of a
diff --git a/doc/crypto/BIO_s_accept.pod b/doc/crypto/BIO_s_accept.pod
index a9259ab217..724f1480df 100644
--- a/doc/crypto/BIO_s_accept.pod
+++ b/doc/crypto/BIO_s_accept.pod
@@ -2,7 +2,6 @@
 
 =head1 NAME
 
-BIO_BIND_NORMAL, BIO_BIND_REUSEADDR_IF_UNUSED, BIO_BIND_REUSEADDR,
 BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, BIO_new_accept,
 BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode,
 BIO_get_bind_mode, BIO_do_accept - accept BIO
@@ -24,10 +23,6 @@ BIO_get_bind_mode, BIO_do_accept - accept BIO
  long BIO_set_bind_mode(BIO *b, long mode);
  long BIO_get_bind_mode(BIO *b);
 
- #define BIO_BIND_NORMAL                0
- #define BIO_BIND_REUSEADDR_IF_UNUSED   1
- #define BIO_BIND_REUSEADDR             2
-
  int BIO_do_accept(BIO *b);
 
 =head1 DESCRIPTION
@@ -82,13 +77,13 @@ chain of BIOs must not be freed after this call, they will
 be automatically freed when the accept BIO is freed.
 
 BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve
-the current bind mode. If BIO_BIND_NORMAL (the default) is set
+the current bind mode. If B<BIO_BIND_NORMAL> (the default) is set
 then another socket cannot be bound to the same port. If
-BIO_BIND_REUSEADDR is set then other sockets can bind to the
-same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and
+B<BIO_BIND_REUSEADDR> is set then other sockets can bind to the
+same port. If B<BIO_BIND_REUSEADDR_IF_UNUSED> is set then and
 attempt is first made to use BIO_BIN_NORMAL, if this fails
 and the port is not in use then a second attempt is made
-using BIO_BIND_REUSEADDR.
+using B<BIO_BIND_REUSEADDR>.
 
 BIO_do_accept() serves two functions. When it is first
 called, after the accept BIO has been setup, it will attempt
diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod
index fb661979d8..cb46546e21 100644
--- a/doc/crypto/BIO_s_bio.pod
+++ b/doc/crypto/BIO_s_bio.pod
@@ -13,22 +13,20 @@ BIO_ctrl_get_read_request, BIO_ctrl_reset_read_request - BIO pair BIO
 
  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
@@ -123,6 +121,11 @@ 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
diff --git a/doc/crypto/BIO_s_fd.pod b/doc/crypto/BIO_s_fd.pod
index 8002ad7754..aa7ba363ad 100644
--- a/doc/crypto/BIO_s_fd.pod
+++ b/doc/crypto/BIO_s_fd.pod
@@ -8,10 +8,10 @@ BIO_s_fd, BIO_set_fd, BIO_get_fd, BIO_new_fd - file descriptor BIO
 
  #include <openssl/bio.h>
 
- const BIO_METHOD *     BIO_s_fd(void);
+ const BIO_METHOD *BIO_s_fd(void);
 
- #define BIO_set_fd(b,fd,c)     BIO_int_ctrl(b,BIO_C_SET_FD,c,fd)
- #define BIO_get_fd(b,c)        BIO_ctrl(b,BIO_C_GET_FD,0,(char *)c)
+ int BIO_set_fd(BIO *b, int fd, int c);
+ int BIO_get_fd(BIO *b, int *c);
 
  BIO *BIO_new_fd(int fd, int close_flag);
 
@@ -27,19 +27,19 @@ If the close flag is set then close() is called on the underlying
 file descriptor when the BIO is freed.
 
 BIO_reset() attempts to change the file pointer to the start of file
-using lseek(fd, 0, 0).
+such as by using B<lseek(fd, 0, 0)>.
 
 BIO_seek() sets the file pointer to position B<ofs> from start of file
-using lseek(fd, ofs, 0).
+such as by using B<lseek(fd, ofs, 0)>.
 
-BIO_tell() returns the current file position by calling lseek(fd, 0, 1).
+BIO_tell() returns the current file position such as by calling
+B<lseek(fd, 0, 1)>.
 
 BIO_set_fd() sets the file descriptor of BIO B<b> to B<fd> and the close
 flag to B<c>.
 
 BIO_get_fd() places the file descriptor in B<c> if it is not NULL, it also
-returns the file descriptor. If B<c> is not NULL it should be of type
-(int *).
+returns the file descriptor.
 
 BIO_new_fd() returns a file descriptor BIO using B<fd> and B<close_flag>.
 
@@ -54,15 +54,12 @@ manual pages.
 File descriptor BIOs should not be used for socket I/O. Use socket BIOs
 instead.
 
+BIO_set_fd() and BIO_get_fd() are implemented as macros.
+
 =head1 RETURN VALUES
 
 BIO_s_fd() returns the file descriptor BIO method.
 
-BIO_reset() returns zero for success and -1 if an error occurred.
-BIO_seek() and BIO_tell() return the current file position or -1
-is an error occurred. These values reflect the underlying lseek()
-behaviour.
-
 BIO_set_fd() always returns 1.
 
 BIO_get_fd() returns the file descriptor or -1 if the BIO has not
@@ -76,6 +73,7 @@ occurred.
 This is a file descriptor BIO version of "Hello World":
 
  BIO *out;
+ 
  out = BIO_new_fd(fileno(stdout), BIO_NOCLOSE);
  BIO_printf(out, "Hello World\n");
  BIO_free(out);
diff --git a/doc/crypto/BIO_set_callback.pod b/doc/crypto/BIO_set_callback.pod
index 219a6dd3eb..42e4545d93 100644
--- a/doc/crypto/BIO_set_callback.pod
+++ b/doc/crypto/BIO_set_callback.pod
@@ -9,16 +9,17 @@ BIO_debug_callback - BIO callback functions
 
  #include <openssl/bio.h>
 
- #define BIO_set_callback(b,cb)         ((b)->callback=(cb))
- #define BIO_get_callback(b)            ((b)->callback)
- #define BIO_set_callback_arg(b,arg)    ((b)->cb_arg=(char *)(arg))
- #define BIO_get_callback_arg(b)                ((b)->cb_arg)
 
- long BIO_debug_callback(BIO *bio,int cmd,const char *argp,int argi,
-        long argl,long ret);
+ typedef long (*BIO_callback_fn)(BIO *b, int oper, const char *argp, int argi,
+                                 long argl, long ret);
 
- typedef long (*callback)(BIO *b, int oper, const char *argp,
-                        int argi, long argl, long retvalue);
+ void BIO_set_callback(BIO *b, BIO_callack_fn cb);
+ BIO_callack_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(BIO *bio, int cmd, const char *argp, int argi,
+                         long argl, long ret);
 
 =head1 DESCRIPTION
 
@@ -32,12 +33,13 @@ used to set and retrieve an argument for use in the callback.
 
 BIO_debug_callback() is a standard debugging callback which prints
 out information relating to each BIO operation. If the callback
-argument is set if is interpreted as a BIO to send the information
+argument is set it is interpreted as a BIO to send the information
 to, otherwise stderr is used.
 
-callback() is the callback function itself. The meaning of each
-argument is described below.
+BIO_callback_fn() is the type of the callback function. The meaning of each
+argument is described below:
 
+=over
 The BIO the callback is attached to is passed in B<b>.
 
 B<oper> is set to the operation being performed. For some operations
@@ -47,19 +49,24 @@ operation, the latter case has B<oper> or'ed with BIO_CB_RETURN.
 The meaning of the arguments B<argp>, B<argi> and B<argl> depends on
 the value of B<oper>, that is the operation being performed.
 
-B<retvalue> is the return value that would be returned to the
+B<ret> is the return value that would be returned to the
 application if no callback were present. The actual value returned
 is the return value of the callback itself. In the case of callbacks
-called before the actual BIO operation 1 is placed in retvalue, if
+called before the actual BIO operation 1 is placed in B<ret>, if
 the return value is not positive it will be immediately returned to
 the application and the BIO operation will not be performed.
 
-The callback should normally simply return B<retvalue> when it has
-finished processing, unless if specifically wishes to modify the
+=back
+
+The callback should normally simply return B<ret> when it has
+finished processing, unless it specifically wishes to modify the
 value returned to the application.
 
 =head1 CALLBACK OPERATIONS
 
+In the notes below, B<callback> defers to the actual callback
+function that is called.
+
 =over 4
 
 =item B<BIO_free(b)>
diff --git a/doc/crypto/BIO_should_retry.pod b/doc/crypto/BIO_should_retry.pod
index 2a6485af9a..d6ddf48e2c 100644
--- a/doc/crypto/BIO_should_retry.pod
+++ b/doc/crypto/BIO_should_retry.pod
@@ -2,8 +2,6 @@
 
 =head1 NAME
 
-BIO_FLAGS_READ, BIO_FLAGS_WRITE, BIO_FLAGS_IO_SPECIAL, BIO_FLAGS_RWS,
-BIO_FLAGS_SHOULD_RETRY,
 BIO_should_read, BIO_should_write,
 BIO_should_io_special, BIO_retry_type, BIO_should_retry,
 BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry
@@ -13,17 +11,11 @@ functions
 
  #include <openssl/bio.h>
 
- #define BIO_should_read(a)             ((a)->flags & BIO_FLAGS_READ)
- #define BIO_should_write(a)            ((a)->flags & BIO_FLAGS_WRITE)
- #define BIO_should_io_special(a)       ((a)->flags & BIO_FLAGS_IO_SPECIAL)
- #define BIO_retry_type(a)              ((a)->flags & BIO_FLAGS_RWS)
- #define BIO_should_retry(a)            ((a)->flags & BIO_FLAGS_SHOULD_RETRY)
-
- #define BIO_FLAGS_READ         0x01
- #define BIO_FLAGS_WRITE        0x02
- #define BIO_FLAGS_IO_SPECIAL   0x04
- #define BIO_FLAGS_RWS (BIO_FLAGS_READ|BIO_FLAGS_WRITE|BIO_FLAGS_IO_SPECIAL)
- #define BIO_FLAGS_SHOULD_RETRY 0x08
+ int BIO_should_read(BIO *b);
+ int BIO_should_write(BIO *b);
+ int BIO_should_io_special(iBIO *b);
+ int BIO_retry_type(BIO *b);
+ int BIO_should_retry(BIO *b);
 
  BIO *BIO_get_retry_BIO(BIO *bio, int *reason);
  int BIO_get_retry_reason(BIO *bio);
@@ -68,6 +60,9 @@ BIO. This would usually only be called by BIO implementations.
 
 =head1 NOTES
 
+BIO_should_read(), BIO_should_write(), BIO_should_io_special(),
+BIO_retry_type(), and BIO_should_retry(), are implemented as macros.
+
 If BIO_should_retry() returns false then the precise "error condition"
 depends on the BIO type that caused it and the return code of the BIO
 operation. For example if a call to BIO_read() on a socket BIO returns
diff --git a/doc/crypto/BN_new.pod b/doc/crypto/BN_new.pod
index ab7c4e5ae4..0277614276 100644
--- a/doc/crypto/BN_new.pod
+++ b/doc/crypto/BN_new.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-BN_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
+BN_new, BN_secure_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
 
 =head1 SYNOPSIS
 
@@ -10,6 +10,8 @@ BN_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
 
  BIGNUM *BN_new(void);
 
+ BIGNUM *BN_secure_new(void);
+
  void BN_clear(BIGNUM *a);
 
  void BN_free(BIGNUM *a);
@@ -19,6 +21,8 @@ BN_new, BN_clear, BN_free, BN_clear_free - allocate and free BIGNUMs
 =head1 DESCRIPTION
 
 BN_new() allocates and initializes a B<BIGNUM> structure.
+BN_secure_new() does the same except that the secure heap
+OPENSSL_secure_malloc(3) is used to store the value.
 
 BN_clear() is used to destroy sensitive data such as keys when they
 are no longer needed. It erases the memory used by B<a> and sets it
@@ -31,8 +35,9 @@ If B<a> is NULL, nothing is done.
 
 =head1 RETURN VALUES
 
-BN_new() returns a pointer to the B<BIGNUM>. If the allocation fails,
-it returns B<NULL> and sets an error code that can be obtained
+BN_new() and BN_secure_new()
+return a pointer to the B<BIGNUM>. If the allocation fails,
+they return B<NULL> and set an error code that can be obtained
 by L<ERR_get_error(3)>.
 
 BN_clear(), BN_free() and BN_clear_free() have no return values.
diff --git a/doc/crypto/BUF_MEM_new.pod b/doc/crypto/BUF_MEM_new.pod
index 1a975776aa..eb85bed896 100644
--- a/doc/crypto/BUF_MEM_new.pod
+++ b/doc/crypto/BUF_MEM_new.pod
@@ -2,7 +2,6 @@
 
 =head1 NAME
 
-BUF_MEM_FLAG_SECURE,
 BUF_MEM_new, BUF_MEM_new_ex, BUF_MEM_free, BUF_MEM_grow
 BUF_MEM_grow_clean, BUF_reverse
 - simple character array structure
@@ -15,8 +14,6 @@ standard C library equivalents
 
  BUF_MEM *BUF_MEM_new(void);
 
- #define BUF_MEM_FLAG_SECURE
-
  BUF_MEM *BUF_MEM_new_ex(unsigned long flags);
 
  void BUF_MEM_free(BUF_MEM *a);
diff --git a/doc/crypto/DEFINE_STACK_OF.pod b/doc/crypto/DEFINE_STACK_OF.pod
index 94e483feff..5acc3e306e 100644
--- a/doc/crypto/DEFINE_STACK_OF.pod
+++ b/doc/crypto/DEFINE_STACK_OF.pod
@@ -3,6 +3,7 @@
 =head1 NAME
 
 DEFINE_STACK_OF, DEFINE_STACK_OF_CONST, DEFINE_SPECIAL_STACK_OF,
+DEFINE_SPECIAL_STACK_OF_CONST,
 OPENSSL_sk_deep_copy, OPENSSL_sk_delete, OPENSSL_sk_delete_ptr,
 OPENSSL_sk_dup, OPENSSL_sk_find, OPENSSL_sk_find_ex, OPENSSL_sk_free,
 OPENSSL_sk_insert, OPENSSL_sk_is_sorted, OPENSSL_sk_new, OPENSSL_sk_new_null,
@@ -22,10 +23,11 @@ stack container
 
  #include <openssl/safestack.h>
 
- #define STACK_OF(TYPE)
- #define DEFINE_STACK_OF
- #define DEFINE_STACK_OF_CONST
- #define DEFINE_SPECIAL_STACK_OF
+ STACK_OF(TYPE)
+ DEFINE_STACK_OF(TYPE)
+ DEFINE_STACK_OF_CONST(TYPE)
+ DEFINE_SPECIAL_STACK_OF(FUNCTYPE, TYPE)
+ DEFINE_SPECIAL_STACK_OF_CONST(FUNCTYPE, TYPE)
 
  typedef int (*sk_TYPE_compfunc)(const TYPE *const *a, const TYPE *const *b);
  typedef TYPE * (*sk_TYPE_copyfunc)(const TYPE *a);
@@ -64,22 +66,28 @@ functions that wrap around the utility B<OPENSSL_sk_> API.
 In the description here, I<TYPE> is used
 as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
 
-DEFINE_STACK_OF(TYPE) creates set of functions for a stack of B<TYPE>. This
+STACK_OF() returns the name for a stack of the specified B<TYPE>.
+DEFINE_STACK_OF() creates set of functions for a stack of B<TYPE>. This
 will mean that type B<TYPE> is stored in each stack, the type is referenced by
 STACK_OF(TYPE) and each function name begins with I<sk_TYPE_>. For example:
 
  TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
 
-DEFINE_STACK_OF_CONST(TYPE) is identical to DEFINE_STACK_OF(TYPE) except
+DEFINE_STACK_OF_CONST() is identical to DEFINE_STACK_OF() except
 each element is constant. For example:
 
  const TYPE *sk_TYPE_value(STACK_OF(TYPE) *sk, int idx);
 
-DEFINE_SPECIAL_STACK_OF(FUNCNAME, TYPE) defines a stack of B<TYPE> but
+DEFINE_SPECIAL_STACK_OF() defines a stack of B<TYPE> but
 each function uses B<FUNCNAME> in the function name. For example:
 
  TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
 
+DEFINE_SPECIAL_STACK_OF_CONST() is similar except that each element is
+constant:
+
+ const TYPE *sk_FUNCNAME_value(STACK_OF(TYPE) *sk, int idx);
+
 sk_TYPE_num() returns the number of elements in B<sk> or -1 if B<sk> is
 B<NULL>.
 
@@ -170,6 +178,9 @@ sk_TYPE_find() and sk_TYPE_find_ex(). They return an index to the
 matching element. In particular B<0> indicates a matching first element.
 A failed search is indicated by a B<-1> return value.
 
+STACK_OF(), DEFINE_STACK_OF(), DEFINE_STACK_OF_CONST(), and
+DEFINE_SPECIAL_STACK_OF() are implemented as macros.
+
 =head1 RETURN VALUES
 
 sk_TYPE_num() returns the number of elements in the stack or B<-1> if the
diff --git a/doc/crypto/ENGINE_add.pod b/doc/crypto/ENGINE_add.pod
index 4e0