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>

7 files changed, 48 insertions, 50 deletions

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);