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>

36 files changed, 279 insertions, 343 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 4e082bc7ef..da86532ad9 100644
--- a/doc/crypto/ENGINE_add.pod
+++ b/doc/crypto/ENGINE_add.pod
@@ -13,7 +13,7 @@ ENGINE_get_destroy_function, ENGINE_get_finish_function,
 ENGINE_get_init_function, ENGINE_get_load_privkey_function,
 ENGINE_get_load_pubkey_function, ENGINE_load_private_key,
 ENGINE_load_public_key, ENGINE_get_RAND, ENGINE_get_RSA, ENGINE_get_id,
-ENGINE_get_name, ENGINE_get_cmd_defns, EVP_CIPHER ENGINE_get_cipher,
+ENGINE_get_name, ENGINE_get_cmd_defns, ENGINE_get_cipher,
 ENGINE_get_digest, ENGINE_add, ENGINE_cmd_is_executable,
 ENGINE_ctrl, ENGINE_ctrl_cmd, ENGINE_ctrl_cmd_string,
 ENGINE_finish, ENGINE_free, ENGINE_get_flags, ENGINE_init,
@@ -525,17 +525,17 @@ this symbol is considered a "generic" command is handled directly by the
 OpenSSL core routines.
 
 It is using these "core" control commands that one can discover the control
-commands implemented by a given ENGINE, specifically the commands;
-
- #define ENGINE_HAS_CTRL_FUNCTION               10
- #define ENGINE_CTRL_GET_FIRST_CMD_TYPE         11
- #define ENGINE_CTRL_GET_NEXT_CMD_TYPE          12
- #define ENGINE_CTRL_GET_CMD_FROM_NAME          13
- #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD      14
- #define ENGINE_CTRL_GET_NAME_FROM_CMD          15
- #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD      16
- #define ENGINE_CTRL_GET_DESC_FROM_CMD          17
- #define ENGINE_CTRL_GET_CMD_FLAGS              18
+commands implemented by a given ENGINE, specifically the commands:
+
+ ENGINE_HAS_CTRL_FUNCTION
+ ENGINE_CTRL_GET_FIRST_CMD_TYPE
+ ENGINE_CTRL_GET_NEXT_CMD_TYPE
+ ENGINE_CTRL_GET_CMD_FROM_NAME
+ ENGINE_CTRL_GET_NAME_LEN_FROM_CMD
+ ENGINE_CTRL_GET_NAME_FROM_CMD
+ ENGINE_CTRL_GET_DESC_LEN_FROM_CMD
+ ENGINE_CTRL_GET_DESC_FROM_CMD
+ ENGINE_CTRL_GET_CMD_FLAGS
 
 Whilst these commands are automatically processed by the OpenSSL framework code,
 they use various properties exposed by each ENGINE to process these
@@ -569,12 +569,12 @@ return properties of the corresponding commands. All except
 ENGINE_CTRL_GET_FLAGS return the string length of a command name or description,
 or populate a supplied character buffer with a copy of the command name or
 description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following
-possible values;
+possible values:
 
- #define ENGINE_CMD_FLAG_NUMERIC                (unsigned int)0x0001
- #define ENGINE_CMD_FLAG_STRING                 (unsigned int)0x0002
- #define ENGINE_CMD_FLAG_NO_INPUT               (unsigned int)0x0004
- #define ENGINE_CMD_FLAG_INTERNAL               (unsigned int)0x0008
+ ENGINE_CMD_FLAG_NUMERIC
+ ENGINE_CMD_FLAG_STRING
+ ENGINE_CMD_FLAG_NO_INPUT
+ ENGINE_CMD_FLAG_INTERNAL
 
 If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely
 informational to the caller - this flag will prevent the command being usable
diff --git a/doc/crypto/ERR_put_error.pod b/doc/crypto/ERR_put_error.pod
index 1ec3575f0d..9d2405e3d3 100644
--- a/doc/crypto/ERR_put_error.pod
+++ b/doc/crypto/ERR_put_error.pod
@@ -49,10 +49,6 @@ the capitalized form such as "SSL3_READ_BYTES" in the above example.
 The trailing section of a reason code (after the "_R_") is translated
 into lower case and underscores changed to spaces.
 
-When you are using new function or reason codes, run B<make errors>.
-The necessary B<#define>s will then automatically be added to the
-sub-library's header file.
-
 Although a library will normally report errors using its own specific
 XXXerr macro, another library's macro can be used. This is normally
 only done when a library wants to include ASN1 code which must use
diff --git a/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod
index 405810ee24..d879ba1cd3 100644
--- a/doc/crypto/EVP_DigestInit.pod
+++ b/doc/crypto/EVP_DigestInit.pod
@@ -3,7 +3,7 @@
 =head1 NAME
 
 EVP_MD_CTX_new, EVP_MD_CTX_reset, EVP_MD_CTX_free, EVP_MD_CTX_copy_ex,
-EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_MAX_MD_SIZE,
+EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex,
 EVP_DigestInit, EVP_DigestFinal, EVP_MD_CTX_copy, EVP_MD_type,
 EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size, EVP_MD_CTX_md, EVP_MD_CTX_size,
 EVP_MD_CTX_block_size, EVP_MD_CTX_type, EVP_md_null, EVP_md2, EVP_md5, EVP_sha1,
@@ -32,8 +32,6 @@ EVP_get_digestbynid, EVP_get_digestbyobj - EVP digest routines
 
  int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
 
- #define EVP_MAX_MD_SIZE 64     /* SHA512 */
-
  int EVP_MD_type(const EVP_MD *md);
  int EVP_MD_pkey_type(const EVP_MD *md);
  int EVP_MD_size(const EVP_MD *md);
diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod
index 093618de9c..bffe72b73a 100644
--- a/doc/crypto/EVP_EncryptInit.pod
+++ b/doc/crypto/EVP_EncryptInit.pod
@@ -82,15 +82,16 @@ EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines
  int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
 
  const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
- #define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
- #define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a))
-
- #define EVP_CIPHER_nid(e)              ((e)->nid)
- #define EVP_CIPHER_block_size(e)       ((e)->block_size)
- #define EVP_CIPHER_key_length(e)       ((e)->key_len)
- #define EVP_CIPHER_iv_length(e)                ((e)->iv_len)
- #define EVP_CIPHER_flags(e)            ((e)->flags)
- #define EVP_CIPHER_mode(e)             ((e)->flags) & EVP_CIPH_MODE)
+ const EVP_CIPHER *EVP_get_cipherbynid(int nid);
+ const EVP_CIPHER *EVP_get_cipherbyobj(const ASN1_OBJECT *a);
+
+ int EVP_CIPHER_nid(const EVP_CIPHER *e);
+ int EVP_CIPHER_block_size(const EVP_CIPHER *e);
+ int EVP_CIPHER_key_length(const EVP_CIPHER *e)
+ int EVP_CIPHER_key_length(const EVP_CIPHER *e);
+ int EVP_CIPHER_iv_length(const EVP_CIPHER *e);
+ unsigned long EVP_CIPHER_flags(const EVP_CIPHER *e);
+ unsigned long EVP_CIPHER_mode(const EVP_CIPHER *e);
  int EVP_CIPHER_type(const EVP_CIPHER *ctx);
 
  const EVP_CIPHER *EVP_CIPHER_CTX_cipher(const EVP_CIPHER_CTX *ctx);
@@ -475,8 +476,6 @@ Sets the CCM nonce (IV) length: this call can only be made before specifying
 an nonce value. The nonce length is given by B<15 - L> so it is 7 by default
 for AES.
 
-
-
 =head1 NOTES
 
 Where possible the B<EVP> interface to symmetric ciphers should be used in
@@ -509,6 +508,8 @@ EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(),
 EVP_CipherInit_ex() and EVP_CipherFinal_ex() because they can reuse an
 existing context without allocating and freeing it up on each call.
 
+EVP_get_cipherbynid(), and EVP_get_cipherbyobj() are implemented as macros.
+
 =head1 BUGS
 
 For RC5 the number of rounds can currently only be set to 8, 12 or 16. This is
diff --git a/doc/crypto/EVP_PKEY_HKDF.pod b/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod
index 61e0eec528..61e0eec528 100644
--- a/doc/crypto/EVP_PKEY_HKDF.pod
+++ b/doc/crypto/EVP_PKEY_CTX_set_hkdf_md.pod
diff --git a/doc/crypto/EVP_PKEY_TLS1_PRF.pod b/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md
index 5c8dd9ddaa..0d57f9fb6a 100644
--- a/doc/crypto/EVP_PKEY_TLS1_PRF.pod
+++ b/doc/crypto/EVP_PKEY_CTX_set_tls1_prf_md
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-EVP_PKEY_TLS1_PRF, EVP_PKEY_CTX_set_tls1_prf_md,
+EVP_PKEY_CTX_set_tls1_prf_md,
 EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed -
 TLS PRF key derivation algorithm
 
@@ -18,7 +18,7 @@ TLS PRF key derivation algorithm
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_TLS1_PRF algorithm implements the PRF key derivation function for
+The B<EVP_PKEY_TLS1_PRF> algorithm implements the PRF key derivation function for
 TLS. It has no associated private key and only implements key derivation
 using EVP_PKEY_derive().
 
diff --git a/doc/crypto/OPENSSL_LH_COMPFUNC.pod b/doc/crypto/OPENSSL_LH_COMPFUNC.pod
index 372f0d952c..e760ae3be7 100644
--- a/doc/crypto/OPENSSL_LH_COMPFUNC.pod
+++ b/doc/crypto/OPENSSL_LH_COMPFUNC.pod
@@ -5,6 +5,7 @@
 DECLARE_LHASH_OF,
 OPENSSL_LH_COMPFUNC, OPENSSL_LH_HASHFUNC, OPENSSL_LH_DOALL_FUNC,
 LHASH_DOALL_ARG_FN_TYPE,
+IMPLEMENT_LHASH_HASH_FN, IMPLEMENT_LHASH_COMP_FN,
 lh_TYPE_new, lh_TYPE_free,
 lh_TYPE_insert, lh_TYPE_delete, lh_TYPE_retrieve,
 lh_TYPE_doall, lh_TYPE_doall_arg, lh_TYPE_error - dynamic hash table
@@ -43,75 +44,52 @@ and value fields.  In the description here, I<TYPE> is used a placeholder
 for any of the OpenSSL datatypes, such as I<SSL_SESSION>.
 
 lh_TYPE_new() creates a new B<LHASH_OF(TYPE)> structure to store
-arbitrary data entries, and provides the 'hash' and 'compare'
+arbitrary data entries, and specifies the 'hash' and 'compare'
 callbacks to be used in organising the table's entries.  The B<hash>
 callback takes a pointer to a table entry as its argument and returns
 an unsigned long hash value for its key field.  The hash value is
 normally truncated to a power of 2, so make sure that your hash
 function returns well mixed low order bits.  The B<compare> callback
 takes two arguments (pointers to two hash table entries), and returns
-0 if their keys are equal, non-zero otherwise.  If your hash table
+0 if their keys are equal, non-zero otherwise.
+
+If your hash table
 will contain items of some particular type and the B<hash> and
 B<compare> callbacks hash/compare these types, then the
-B<DECLARE_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be
+B<IMPLEMENT_LHASH_HASH_FN> and B<IMPLEMENT_LHASH_COMP_FN> macros can be
 used to create callback wrappers of the prototypes required by
-lh_TYPE_new().  These provide per-variable casts before calling the
-type-specific callbacks written by the application author.  These
-macros, as well as those used for the "doall" callbacks, are defined
-as;
-
- #define DECLARE_LHASH_HASH_FN(name, o_type) \
-         unsigned long name##_LHASH_HASH(const void *);
- #define IMPLEMENT_LHASH_HASH_FN(name, o_type) \
-         unsigned long name##_LHASH_HASH(const void *arg) { \
-                 const o_type *a = arg; \
-                 return name##_hash(a); }
- #define LHASH_HASH_FN(name) name##_LHASH_HASH
-
- #define DECLARE_LHASH_COMP_FN(name, o_type) \
-         int name##_LHASH_COMP(const void *, const void *);
- #define IMPLEMENT_LHASH_COMP_FN(name, o_type) \
-         int name##_LHASH_COMP(const void *arg1, const void *arg2) { \
-                 const o_type *a = arg1;                    \
-                 const o_type *b = arg2; \
-                 return name##_cmp(a,b); }
- #define LHASH_COMP_FN(name) name##_LHASH_COMP
-
- #define DECLARE_LHASH_DOALL_FN(name, o_type) \
-         void name##_LHASH_DOALL(void *);
- #define IMPLEMENT_LHASH_DOALL_FN(name, o_type) \
-         void name##_LHASH_DOALL(void *arg) { \
-                 o_type *a = arg; \
-                 name##_doall(a); }
- #define LHASH_DOALL_FN(name) name##_LHASH_DOALL
-
- #define DECLARE_LHASH_DOALL_ARG_FN(name, o_type, a_type) \
-         void name##_LHASH_DOALL_ARG(void *, void *);
- #define IMPLEMENT_LHASH_DOALL_ARG_FN(name, o_type, a_type) \
-         void name##_LHASH_DOALL_ARG(void *arg1, void *arg2) { \
-                 o_type *a = arg1; \
-                 a_type *b = arg2; \
-                 name##_doall_arg(a, b); }
- #define LHASH_DOALL_ARG_FN(name) name##_LHASH_DOALL_ARG
-
- An example of a hash table storing (pointers to) structures of type 'STUFF'
- could be defined as follows;
-
- /* Calculates the hash value of 'tohash' (implemented elsewhere) */
- unsigned long STUFF_hash(const STUFF *tohash);
- /* Orders 'arg1' and 'arg2' (implemented elsewhere) */
- int stuff_cmp(const STUFF *arg1, const STUFF *arg2);
- /* Create the type-safe wrapper functions for use in the LHASH internals */
- static IMPLEMENT_LHASH_HASH_FN(stuff, STUFF);
- static IMPLEMENT_LHASH_COMP_FN(stuff, STUFF);
- /* ... */
- int main(int argc, char *argv[]) {
-         /* Create the new hash table using the hash/compare wrappers */
-         LHASH_OF(STUFF) *hashtable = lh_STUFF_new(LHASH_HASH_FN(STUFF_hash),
-                                   LHASH_COMP_FN(STUFF_cmp));
-         /* ... */
+lh_TYPE_new() as shown in this example:
+
+ /*
+  * Implement the hash and compare functions; "stuff" can be any word.
+  */
+ static unsigned long stuff_hash(const TYPE *a)
+ {
+     ...
+ }
+ static int stuff_cmp(const TYPE *a, const TYPE *b)
+ {
+     ...
  }
 
+ /*
+  * Implement the wrapper functions.
+  */
+ static IMPLEMENT_LHASH_HASH_FN(stuff, TYPE)
+ static IMPLEMENT_LHASH_COMP_FN(stuff, TYPE)
+
+If the type is going to be used in several places, the following macros
+can be used in a common header file to declare the function wrappers:
+
+ DECLARE_LHASH_HASH_FN(stuff, TYPE)
+ DECLARE_LHASH_COMP_FN(stuff, TYPE)
+
+Then a hash table of TYPE objects can be created using this:
+
+ LHASH_OF(TYPE) *htable;
+
+ htable = lh_TYPE_new(LHASH_HASH_FN(stuff), LHASH_COMP_FN(stuff));
+
 lh_TYPE_free() frees the B<LHASH_OF(TYPE)> structure
 B<table>. Allocated hash table entries will not be freed; consider
 using lh_TYPE_doall() to deallocate any remaining entries in the
@@ -129,24 +107,20 @@ is a structure with the key field(s) set; the function will return a
 pointer to a fully populated structure.
 
 lh_TYPE_doall() will, for every entry in the hash table, call
-B<func> with the data item as its parameter.  For lh_TYPE_doall()
-and lh_TYPE_doall_arg(), function pointer casting should be avoided
-in the callbacks (see B<NOTE>) - instead use the declare/implement
-macros to create type-checked wrappers that cast variables prior to
-calling your type-specific callbacks.  An example of this is
-illustrated here where the callback is used to cleanup resources for
-items in the hash table prior to the hashtable itself being
-deallocated:
+B<func> with the data item as its parameter.
+For example:
 
  /* Cleans up resources belonging to 'a' (this is implemented elsewhere) */
- void STUFF_cleanup_doall(STUFF *a);
- /* Implement a prototype-compatible wrapper for "STUFF_cleanup" */
- IMPLEMENT_LHASH_DOALL_FN(STUFF_cleanup, STUFF)
-         /* ... then later in the code ... */
- /* So to run "STUFF_cleanup" against all items in a hash table ... */
- lh_STUFF_doall(hashtable, LHASH_DOALL_FN(STUFF_cleanup));
+ void TYPE_cleanup_doall(TYPE *a);
+
+ /* Implement a prototype-compatible wrapper for "TYPE_cleanup" */
+ IMPLEMENT_LHASH_DOALL_FN(TYPE_cleanup, TYPE)
+
+ /* Call "TYPE_cleanup" against all items in a hash table. */
+ lh_TYPE_doall(hashtable, LHASH_DOALL_FN(TYPE_cleanup));
+
  /* Then the hash table itself can be deallocated */
- lh_STUFF_free(hashtable);
+ lh_TYPE_free(hashtable);
 
 When doing this, be careful if you delete entries from the hash table
 in your callbacks: the table may decrease in size, moving the item
@@ -169,13 +143,14 @@ this is demonstrated here (printing all hash table entries to a BIO
 that is provided by the caller):
 
  /* Prints item 'a' to 'output_bio' (this is implemented elsewhere) */
- void STUFF_print_doall_arg(const STUFF *a, BIO *output_bio);
- /* Implement a prototype-compatible wrapper for "STUFF_print" */
- static IMPLEMENT_LHASH_DOALL_ARG_FN(STUFF, const STUFF, BIO)
-         /* ... then later in the code ... */
+ void TYPE_print_doall_arg(const TYPE *a, BIO *output_bio);
+
+ /* Implement a prototype-compatible wrapper for "TYPE_print" */
+ static IMPLEMENT_LHASH_DOALL_ARG_FN(TYPE, const TYPE, BIO)
+
  /* Print out the entire hashtable to a particular BIO */
- lh_STUFF_doall_arg(hashtable, LHASH_DOALL_ARG_FN(STUFF_print), BIO,
-                    logging_bio);
+ lh_TYPE_doall_arg(hashtable, LHASH_DOALL_ARG_FN(TYPE_print), BIO,
+                   logging_bio);
 
 
 lh_TYPE_error() can be used to determine if an error occurred in the last
@@ -226,7 +201,7 @@ elsewhere in their code) - in this case the LHASH prototypes are
 appropriate as-is.  Conversely, if the caller is responsible for the
 life-time of the data in question, then they may well wish to make
 modifications to table item passed back in the lh_doall() or
-lh_doall_arg() callbacks (see the "STUFF_cleanup" example above).  If
+lh_doall_arg() callbacks (see the "TYPE_cleanup" example above).  If
 so, the caller can either cast the "const" away (if they're providing
 the raw callbacks themselves) or use the macros to declare/implement
 the wrapper functions without "const" types.
diff --git a/doc/crypto/OPENSSL_ia32cap.pod b/doc/crypto/OPENSSL_ia32cap.pod
index 7b8629def0..7ea70c0fae 100644
--- a/doc/crypto/OPENSSL_ia32cap.pod
+++ b/doc/crypto/OPENSSL_ia32cap.pod
@@ -126,6 +126,8 @@ requirements are summarized in below table:
    AVX2        | 2.22   | 2.10   | 3.1
    AVX512      | 2.25   | 2.11.8 | 3.6
 
+B<OPENSSL_ia32cap> is a macro returning the first word of the vector.
+
 =head1 COPYRIGHT
 
 Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/crypto/OPENSSL_malloc.pod b/doc/crypto/OPENSSL_malloc.pod
index 9760135ee9..574db8a5f3 100644
--- a/doc/crypto/OPENSSL_malloc.pod
+++ b/doc/crypto/OPENSSL_malloc.pod
@@ -2,8 +2,6 @@
 
 =head1 NAME
 
-CRYPTO_MEM_CHECK_OFF, CRYPTO_MEM_CHECK_ON,
-CRYPTO_MEM_CHECK_DISABLE, CRYPTO_MEM_CHECK_ENABLE,
 OPENSSL_malloc_init,
 OPENSSL_malloc, OPENSSL_zalloc, OPENSSL_realloc, OPENSSL_free,
 OPENSSL_clear_realloc, OPENSSL_clear_free, OPENSSL_cleanse,
@@ -62,11 +60,6 @@ CRYPTO_mem_leaks, CRYPTO_mem_leaks_fp - Memory allocation functions
 
  int CRYPTO_set_mem_debug(int onoff)
 
- #define CRYPTO_MEM_CHECK_OFF
- #define CRYPTO_MEM_CHECK_ON
- #define CRYPTO_MEM_CHECK_DISABLE
- #define CRYPTO_MEM_CHECK_ENABLE
-
  int CRYPTO_mem_ctrl(int mode);
 
  int OPENSSL_mem_debug_push(const char *info)
@@ -150,9 +143,6 @@ To enable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of
 the B<CRYPTO_MEM_CHECK_ON>.
 To disable tracking call CRYPTO_mem_ctrl() with a B<mode> argument of
 the B<CRYPTO_MEM_CHECK_OFF>.
-The B<CRYPTO_MEM_CHECK_DISABLE> and B<CRYPTO_MEM_CHECK_ENABLE> modes
-are used internally within OpenSSL to temporarily suspend and resume
-tracking.
 
 While checking memory, it can be useful to store additional context
 about what is being done.
diff --git a/doc/crypto/PEM_read.pod b/doc/crypto/PEM_read.pod
index 167693dec1..66cbc7d243 100644
--- a/doc/crypto/PEM_read.pod
+++ b/doc/crypto/PEM_read.pod
@@ -3,8 +3,7 @@
 =head1 NAME
 
 PEM_write, PEM_write_bio,
-PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO,
-pem_password_cb
+PEM_read, PEM_read_bio, PEM_do_header, PEM_get_EVP_CIPHER_INFO
 - PEM encoding routines
 
 =head1 SYNOPSIS
@@ -25,8 +24,6 @@ pem_password_cb
  int PEM_do_header(EVP_CIPHER_INFO *cinfo, unsigned char *data, long *len,
                    pem_password_cb *cb, void *u);
 
- typedef int (*pem_password_cb)(char *buf, int size, int rwflag, void *u);
-
 =head1 DESCRIPTION
 
 These functions read and write PEM-encoded objects, using the PEM
diff --git a/doc/crypto/PEM_read_CMS.pod b/doc/crypto/PEM_read_CMS.pod
index 5a799f9e89..649c8089a9 100644
--- a/doc/crypto/PEM_read_CMS.pod
+++ b/doc/crypto/PEM_read_CMS.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+DECLARE_PEM_rw,
 PEM_read_CMS,
 PEM_read_bio_CMS,
 PEM_write_CMS,
@@ -43,7 +44,7 @@ PEM_write_bio_SSL_SESSION
 
  #include <openssl/pem.h>
 
- #define DECLARE_PEM_rw(name, TYPE) ...
+ DECLARE_PEM_rw(name, TYPE)
 
  TYPE *PEM_read_TYPE(FILE *fp, TYPE **a, pem_password_cb *cb, void *u);
  TYPE *PEM_read_bio_TYPE(BIO *bp, TYPE **a, pem_password_cb *cb, void *u);
@@ -54,6 +55,8 @@ PEM_write_bio_SSL_SESSION
 
 In the description below, I<TYPE> is used
 as a placeholder for any of the OpenSSL datatypes, such as I<X509>.
+The macro B<DECLARE_PEM_rw> expands to the set of declarations shown in
+the next four lines of the synopsis.
 
 These routines convert between local instances of ASN1 datatypes and
 the PEM encoding.  For more information on the templates, see
diff --git a/doc/crypto/PEM_read_bio_PrivateKey.pod b/doc/crypto/PEM_read_bio_PrivateKey.pod
index dd5a230998..fbfe975be0 100644
--- a/doc/crypto/PEM_read_bio_PrivateKey.pod
+++ b/doc/crypto/PEM_read_bio_PrivateKey.pod
@@ -2,6 +2,7 @@
 
 =head1 NAME
 
+pem_password_cb,
 PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
 PEM_write_bio_PrivateKey_traditional, PEM_write_PrivateKey,
 PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey,
@@ -29,6 +30,8 @@ PEM_write_bio_PKCS7, PEM_write_PKCS7 - PEM routines
 
  #include <openssl/pem.h>
 
+ typedef int (*pem_password_cb)(char *buf, int size, int rwflag, void *u);
+
  EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
                                    pem_password_cb *cb, void *u);
  EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
diff --git a/doc/crypto/PKCS7_verify.pod b/doc/crypto/PKCS7_verify.pod
index 6cf80df333..c34808eced 100644
--- a/doc/crypto/PKCS7_verify.pod
+++ b/doc/crypto/PKCS7_verify.pod
@@ -2,15 +2,12 @@
 
 =head1 NAME
 
-PKCS7_NO_DUAL_CONTENT,
 PKCS7_verify, PKCS7_get0_signers - verify a PKCS#7 signedData structure
 
 =head1 SYNOPSIS
 
  #include <openssl/pkcs7.h>
 
- #define PKCS7_NO_DUAL_CONTENT
-
  int PKCS7_verify(PKCS7 *p7, STACK_OF(X509) *certs, X509_STORE *store, BIO *indata, BIO *out, int flags);
 
  STACK_OF(X509) *PKCS7_get0_signers(PKCS7 *p7, STACK_OF(X509) *certs, int flags);
diff --git a/doc/crypto/UI_new.pod b/doc/crypto/UI_new.pod
index 72a2ea7095..9abb697807 100644
--- a/doc/crypto/UI_new.pod
+++ b/doc/crypto/UI_new.pod
@@ -2,10 +2,7 @@
 
 =head1 NAME
 
-UI, UI_METHOD, UI_INPUT_FLAG_ECHO,
-UI_INPUT_FLAG_DEFAULT_PWD,
-UI_CTRL_PRINT_ERRORS,
-UI_CTRL_IS_REDOABLE,
+UI, UI_METHOD,
 UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,
 UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,
 UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,
@@ -44,10 +41,6 @@ UI_set_method, UI_OpenSSL, - user interface
  int UI_add_error_string(UI *ui, const char *text);
  int UI_dup_error_string(UI *ui, const char *text);
 
- /* These are the possible flags.  They can be or'ed together. */
- #define UI_INPUT_FLAG_ECHO             0x01
- #define UI_INPUT_FLAG_DEFAULT_PWD      0x02
-
  char *UI_construct_prompt(UI *ui_method,
         const char *object_desc, const char *object_name);
 
@@ -59,8 +52,6 @@ UI_set_method, UI_OpenSSL, - user interface
  int UI_process(UI *ui);
 
  int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
- #define UI_CTRL_PRINT_ERRORS           1
- #define UI_CTRL_IS_REDOABLE            2
 
  void UI_set_default_method(const UI_METHOD *meth);
  const UI_METHOD *UI_get_default_method(void);
@@ -134,10 +125,10 @@ The difference between the two is only conceptual.  With the builtin method,
 there's no technical difference between them.  Other methods may make a
 difference between them, however.
 
-The flags currently supported are UI_INPUT_FLAG_ECHO, which is relevant for
+The flags currently supported are B<UI_INPUT_FLAG_ECHO>, which is relevant for
 UI_add_input_string() and will have the users response be echoed (when
 prompting for a password, this flag should obviously not be used, and
-UI_INPUT_FLAG_DEFAULT_PWD, which means that a default password of some
+B<UI_INPUT_FLAG_DEFAULT_PWD>, which means that a default password of some
 sort will be used (completely depending on the application and the UI
 method).
 
@@ -170,9 +161,9 @@ UI_process() goes through the information given so far, does all the printing
 and prompting and returns.
 
 UI_ctrl() adds extra control for the application author.  For now, it
-understands two commands: UI_CTRL_PRINT_ERRORS, which makes UI_process()
+understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process()
 print the OpenSSL error stack as part of processing the UI, and
-UI_CTRL_IS_REDOABLE, which returns a flag saying if the used UI can
+B<UI_CTRL_IS_REDOABLE>, which returns a flag saying if the used UI can
 be used again or not.
 
 UI_set_default_method() changes the default UI method to the one given.
diff --git a/doc/crypto/X509_dup.pod b/doc/crypto/X509_dup.pod
index b93c228738..03a81f0731 100644
--- a/doc/crypto/X509_dup.pod
+++ b/doc/crypto/X509_dup.pod
@@ -239,8 +239,8 @@ X509_dup,
 
  #include <openssl/asn1t.h>
 
- #define DECLARE_ASN1_FUNCTIONS(type) ...
- #define IMPLEMENT_ASN1_FUNCTIONS(stname) ...
+ DECLARE_ASN1_FUNCTIONS(type)
+ IMPLEMENT_ASN1_FUNCTIONS(stname)
 
  typedef struct ASN1_ITEM_st ASN1_ITEM;
 
@@ -250,7 +250,6 @@ X509_dup,
  void TYPE_free(TYPE *a);
  int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx);
 
-
 =head1 DESCRIPTION
 
 In the description below, I<TYPE> is used
diff --git a/doc/crypto/bio.pod b/doc/crypto/bio.pod
index 5a305c6a29..1e1dd02106 100644
--- a/doc/crypto/bio.pod
+++ b/doc/crypto/bio.pod
@@ -6,6 +6,8 @@
 
 bio - Basic I/O abstraction
 
+=for comment generic
+
 =head1 SYNOPSIS
 
  #include <openssl/bio.h>
diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod
index c199b317a7..29387d343f 100644
--- a/doc/ssl/SSL_CTX_new.pod
+++ b/doc/ssl/SSL_CTX_new.pod
@@ -24,9 +24,9 @@ functions
  const SSL_METHOD *TLS_server_method(void);
  const SSL_METHOD *TLS_client_method(void);
 
- #define SSLv23_method           TLS_method
- #define SSLv23_server_method    TLS_server_method
- #define SSLv23_client_method    TLS_client_method
+ const SSL_METHOD *SSLv23_method(void);
+ const SSL_METHOD *SSLv23_server_method(void);
+ const SSL_METHOD *SSLv23_client_method(void);
 
  #ifndef OPENSSL_NO_SSL3_METHOD
  const SSL_METHOD *SSLv3_method(void);
diff --git a/doc/ssl/SSL_CTX_set_default_passwd_cb.pod b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
index fb448073f9..2196906141 100644
--- a/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
+++ b/doc/ssl/SSL_CTX_set_default_passwd_cb.pod
@@ -2,7 +2,6 @@
 
 =head1 NAME
 
-SSL_CTX_passwd_cb,
 SSL_CTX_set_default_passwd_cb, SSL_CTX_set_default_passwd_cb_userdata,
 SSL_CTX_get_default_passwd_cb, SSL_CTX_get_default_passwd_cb_userdata,
 SSL_set_default_passwd_cb, SSL_set_default_passwd_cb_userdata,
@@ -13,18 +12,16 @@ get passwd callback for encrypted PEM file handling
 
  #include <openssl/ssl.h>
 
- void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, SSL_CTX_passwd_cb *cb);
+ void SSL_CTX_set_default_passwd_cb(SSL_CTX *ctx, pem_password_cb *cb);
  void SSL_CTX_set_default_passwd_cb_userdata(SSL_CTX *ctx, void *u);
- SSL_CTX_passwd_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx);
+ pem_password_cb *SSL_CTX_get_default_passwd_cb(SSL_CTX *ctx);
  void *SSL_CTX_get_default_passwd_cb_userdata(SSL_CTX *ctx);
 
- void SSL_set_default_passwd_cb(SSL *s, SSL_CTX_passwd_cb *cb);
+ void SSL_set_default_passwd_cb(SSL *s, pem_password_cb *cb);
  void SSL_set_default_passwd_cb_userdata(SSL *s, void *u);
- SSL_CTX_passwd_cb *SSL_get_default_passwd_cb(SSL *s);
+ pem_password_cb *SSL_get_default_passwd_cb(SSL *s);
  void *SSL_get_default_passwd_cb_userdata(SSL *s);
 
- typedef int (*SSL_CTX_passwd_cb)(char *buf, int size, int rwflag, void *u);
-
 =head1 DESCRIPTION
 
 SSL_CTX_set_default_passwd_cb() sets the default password callback called
@@ -46,12 +43,14 @@ SSL_get_default_passwd_cb() and SSL_get_default_passwd_cb_userdata() perform
 the same function as their SSL_CTX counterparts, but using an SSL object.
 
 The password callback, which must be provided by the application, hands back the
-password to be used during decryption. On invocation a pointer to userdata
+password to be used during decryption.
+On invocation a pointer to userdata
 is provided. The function must store the password into the provided buffer
 B<buf> which is of size B<size>. The actual length of the password must
 be returned to the calling function. B<rwflag> indicates whether the
 callback is used for reading/decryption (rwflag=0) or writing/encryption
 (rwflag=1).
+For more details, see L<pem_password_cb(3)>.
 
 =head1 NOTES
 
diff --git a/doc/ssl/SSL_CTX_set_read_ahead.pod b/doc/ssl/SSL_CTX_set_read_ahead.pod
index d2b584d35c..bea8390085 100644
--- a/doc/ssl/SSL_CTX_set_read_ahead.pod
+++ b/doc/ssl/SSL_CTX_set_read_ahead.pod
@@ -2,21 +2,21 @@
 
 =head1 NAME
 
-SSL_CTX_set_read_ahead, SSL_CTX_set_default_read_ahead, SSL_CTX_get_read_ahead,
-SSL_CTX_get_default_read_ahead, SSL_set_read_ahead, SSL_get_read_ahead
+SSL_CTX_set_read_ahead, SSL_CTX_get_read_ahead,
+SSL_set_read_ahead, SSL_get_read_ahead,
+SSL_CTX_get_default_read_ahead
 - manage whether to read as many input bytes as possible
 
 =head1 SYNOPSIS
 
  #include <openssl/ssl.h>
 
- int SSL_get_read_ahead(const SSL *s);
  void SSL_set_read_ahead(SSL *s, int yes);
+ int SSL_get_read_ahead(const SSL *s);
 
- #define SSL_CTX_get_default_read_ahead(ctx)
- #define SSL_CTX_set_default_read_ahead(ctx,m)
- #define SSL_CTX_get_read_ahead(ctx)
- #define SSL_CTX_set_read_ahead(ctx,m)
+ SSL_CTX_set_read_ahead(SSL_CTX *ctx, int yes);
+ long SSL_CTX_get_read_ahead(SSL_CTX *ctx);
+ long SSL_CTX_get_default_read_ahead(SSL_CTX *ctx);
 
 =head1 DESCRIPTION
 
@@ -27,9 +27,7 @@ the underlying BIO (where B<y> > B<x>), then OpenSSL will read all B<y> bytes
 into its buffer (providing that the buffer is large enough) if reading ahead is
 on, or B<x> bytes otherwise. The parameter B<yes> or B<m> should be 0 to ensure
 reading ahead is off, or non zero otherwise.
-
-SSL_CTX_set_default_read_ahead is a synonym for SSL_CTX_set_read_ahead, and
-SSL_CTX_get_default_read_ahead is a synonym for SSL_CTX_get_read_ahead.
+SSL_CTX_set_default_read_ahead() is identical to SSL_CTX_set_read_ahead().
 
 SSL_CTX_get_read_ahead() and SSL_get_read_ahead() indicate whether reading
 ahead has been set or not.
diff --git a/doc/ssl/SSL_CTX_set_split_send_fragment.pod b/doc/ssl/SSL_CTX_set_split_send_fragment.pod
index a1f42e2eaf..accf5af247 100644
--- a/doc/ssl/SSL_CTX_set_split_send_fragment.pod
+++ b/doc/ssl/SSL_CTX_set_split_send_fragment.pod
@@ -12,18 +12,14 @@ fragment sizes and pipelining operations
 
  #include <openssl/ssl.h>
 
- # define SSL_CTX_set_max_send_fragment(ctx,m) \
-         SSL_CTX_ctrl(ctx,SSL_CTRL_SET_MAX_SEND_FRAGMENT,m,NULL)
- # define SSL_set_max_send_fragment(ssl,m) \
-         SSL_ctrl(ssl,SSL_CTRL_SET_MAX_SEND_FRAGMENT,m,NULL)
- # define SSL_CTX_set_max_pipelines(ctx,m) \
-         SSL_CTX_ctrl(ctx,SSL_CTRL_SET_MAX_PIPELINES,m,NULL)
- # define SSL_set_max_pipelines(ssl,m) \
-         SSL_ctrl(ssl,SSL_CTRL_SET_MAX_PIPELINES,m,NULL)
- # define SSL_CTX_set_split_send_fragment(ctx,m) \
-         SSL_CTX_ctrl(ctx,SSL_CTRL_SET_SPLIT_SEND_FRAGMENT,m,NULL)
- # define SSL_set_split_send_fragment(ssl,m) \
-         SSL_ctrl(ssl,SSL_CTRL_SET_SPLIT_SEND_FRAGMENT,m,NULL)
+ long SSL_CTX_set_max_send_fragment(SSL_CTX *ctx, long);
+ long SSL_set_max_send_fragment(SSL *ssl, long m);
+
+ long SSL_CTX_set_max_pipelines(SSL_CTX *ctx, long m);
+ long SSL_set_max_pipelines(SSL_CTX *ssl, long m);
+
+ long SSL_CTX_set_split_send_fragment(SSL_CTX *ctx, long m);
+ long SSL_set_split_send_fragment(SSL *ssl, long m);
 
  void SSL_CTX_set_default_read_buffer_len(SSL_CTX *ctx, size_t len);
  void SSL_set_default_read_buffer_len(SSL *s, size_t len);
diff --git a/doc/ssl/SSL_get_current_cipher.pod b/doc/ssl/SSL_get_current_cipher.pod
index 0fdf60f6c1..4b53063e08 100644
--- a/doc/ssl/SSL_get_current_cipher.pod
+++ b/doc/ssl/SSL_get_current_cipher.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-SSL_get_current_cipher, SSL_get_cipher, SSL_get_cipher_name,
+SSL_get_current_cipher, SSL_get_cipher_name,
 SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection
 
 =head1 SYNOPSIS
@@ -10,32 +10,35 @@ SSL_get_cipher_bits, SSL_get_cipher_version - get SSL_CIPHER of a connection
  #include <openssl/ssl.h>
 
  SSL_CIPHER *SSL_get_current_cipher(const SSL *ssl);
- #define SSL_get_cipher(s) \
-                SSL_CIPHER_get_name(SSL_get_current_cipher(s))
- #define SSL_get_cipher_name(s) \
-                SSL_CIPHER_get_name(SSL_get_current_cipher(s))
- #define SSL_get_cipher_bits(s,np) \
-                SSL_CIPHER_get_bits(SSL_get_current_cipher(s),np)
- #define SSL_get_cipher_version(s) \
-                SSL_CIPHER_get_version(SSL_get_current_cipher(s))
+
+ const char *SSL_get_cipher_name(const SSL *s);
+ const char *SSL_get_cipher(const SSL *s);
+ int SSL_get_cipher_bits(const SSL *s, int *np) \
+ const char *SSL_get_cipher_version(const SSL *s);
 
 =head1 DESCRIPTION
 
 SSL_get_current_cipher() returns a pointer to an SSL_CIPHER object containing
 the description of the actually used cipher of a connection established with
 the B<ssl> object.
+See L<SSL_CIPHER_get_name(3)> for more details.
 
-SSL_get_cipher() and SSL_get_cipher_name() are identical macros to obtain the
-name of the currently used cipher. SSL_get_cipher_bits() is a
+SSL_get_cipher_name() obtains the
+name of the currently used cipher.
+SSL_get_cipher() is identical to SSL_get_cipher_name().
+SSL_get_cipher_bits() is a
 macro to obtain the number of secret/algorithm bits used and
 SSL_get_cipher_version() returns the protocol name.
-See L<SSL_CIPHER_get_name(3)> for more details.
 
 =head1 RETURN VALUES
 
-SSL_get_current_cipher() returns the cipher actually used or NULL, when
+SSL_get_current_cipher() returns the cipher actually used, or NULL if
 no session has been established.
 
+=head1 NOTES
+
+These are implemented as macros.
+
 =head1 SEE ALSO
 
 L<ssl(3)>, L<SSL_CIPHER_get_name(3)>
diff --git a/doc/ssl/SSL_library_init.pod b/doc/ssl/SSL_library_init.pod
index 57b65d5d56..6b921f66e7 100644
--- a/doc/ssl/SSL_library_init.pod
+++ b/doc/ssl/SSL_library_init.pod
@@ -10,13 +10,15 @@ SSL_library_init, OpenSSL_add_ssl_algorithms,
  #include <openssl/ssl.h>
 
  int SSL_library_init(void);
- #define OpenSSL_add_ssl_algorithms()    SSL_library_init()
+
+ int OpenSSL_add_ssl_algorithms(void);
 
 =head1 DESCRIPTION
 
 SSL_library_init() registers the available SSL/TLS ciphers and digests.
 
-OpenSSL_add_ssl_algorithms() is a synonym for SSL_library_init().
+OpenSSL_add_ssl_algorithms() is a synonym for SSL_library_init() and is
+implemented as a macro.
 
 =head1 NOTES
 
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index dfd83ead2d..eb63485b36 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -318,7 +318,7 @@ protocol context defined in the B<SSL_CTX> structure.
 
 =item LHASH *B<SSL_CTX_sessions>(SSL_CTX *ctx);
 
-=item void B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg);
+=item int B<SSL_CTX_set_app_data>(SSL_CTX *ctx, void *arg);
 
 =item void B<SSL_CTX_set_cert_store>(SSL_CTX *ctx, X509_STORE *cs);
 
@@ -437,7 +437,7 @@ sessions defined in the B<SSL_SESSION> structures.
 
 =item int B<SSL_SESSION_print_fp>(FILE *fp, const SSL_SESSION *x);
 
-=item void B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a);
+=item int B<SSL_SESSION_set_app_data>(SSL_SESSION *s, char *a);
 
 =item int B<SSL_SESSION_set_ex_data>(SSL_SESSION *s, int idx, char *arg);