Unify <TYPE>_up_ref methods signature and behaviour.

Add a status return value instead of void.
Add some sanity checks on reference counter value.
Update the docs.

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

5 files changed, 12 insertions, 8 deletions

diff --git a/doc/crypto/EVP_PKEY_new.pod b/doc/crypto/EVP_PKEY_new.pod
index 05ac08795e..b639c66454 100644
--- a/doc/crypto/EVP_PKEY_new.pod
+++ b/doc/crypto/EVP_PKEY_new.pod
@@ -9,7 +9,7 @@ EVP_PKEY_new, EVP_PKEY_up_ref, EVP_PKEY_free - private key allocation functions.
  #include <openssl/evp.h>
 
  EVP_PKEY *EVP_PKEY_new(void);
- void EVP_PKEY_up_ref(EVP_PKEY *key);
+ int EVP_PKEY_up_ref(EVP_PKEY *key);
  void EVP_PKEY_free(EVP_PKEY *key);
 
 
@@ -37,7 +37,7 @@ used.
 EVP_PKEY_new() returns either the newly allocated B<EVP_PKEY> structure or
 B<NULL> if an error occurred.
 
-EVP_PKEY_up_ref() and EVP_PKEY_free() do not return a value.
+EVP_PKEY_up_ref() returns 1 for success and 0 for failure.
 
 =head1 SEE ALSO
 
diff --git a/doc/crypto/X509_new.pod b/doc/crypto/X509_new.pod
index 8db6cdb245..484408c4b7 100644
--- a/doc/crypto/X509_new.pod
+++ b/doc/crypto/X509_new.pod
@@ -10,7 +10,7 @@ X509_new, X509_free, X509_up_ref - X509 certificate ASN1 allocation functions
 
  X509 *X509_new(void);
  void X509_free(X509 *a);
- void X509_up_ref(X509 *a);
+ int X509_up_ref(X509 *a);
  STACK_OF(X509) *X509_chain_up_ref(STACK_OF(X509) *x);
 
 =head1 DESCRIPTION
@@ -46,7 +46,7 @@ If the allocation fails, X509_new() returns B<NULL> and sets an error
 code that can be obtained by L<ERR_get_error(3)>.
 Otherwise it returns a pointer to the newly allocated structure.
 
-X509_free() and X509_up_ref() do not return a value.
+X509_up_ref() returns 1 for success and 0 for failure.
 
 X509_chain_up_ref() returns a copy of the stack or B<NULL> if an error
 occurred.
diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod
index f2cdc717ef..8f232a0c6f 100644
--- a/doc/ssl/SSL_CTX_new.pod
+++ b/doc/ssl/SSL_CTX_new.pod
@@ -17,7 +17,7 @@ functions
  #include <openssl/ssl.h>
 
  SSL_CTX *SSL_CTX_new(const SSL_METHOD *method);
- void SSL_CTX_up_ref(SSL_CTX *ctx);
+ int SSL_CTX_up_ref(SSL_CTX *ctx);
 
  const SSL_METHOD *TLS_method(void);
  const SSL_METHOD *TLS_server_method(void);
@@ -184,6 +184,8 @@ the reason.
 
 The return value points to an allocated SSL_CTX object.
 
+SSL_CTX_up_ref() returns 1 for success and 0 for failure.
+
 =back
 
 =head1 HISTORY
diff --git a/doc/ssl/SSL_new.pod b/doc/ssl/SSL_new.pod
index f0e07951e3..cee6b24858 100644
--- a/doc/ssl/SSL_new.pod
+++ b/doc/ssl/SSL_new.pod
@@ -9,7 +9,7 @@ SSL_new, SSL_up_ref - create a new SSL structure for a connection
  #include <openssl/ssl.h>
 
  SSL *SSL_new(SSL_CTX *ctx);
- void SSL_up_ref(SSL *s);
+ int SSL_up_ref(SSL *s);
 
 =head1 DESCRIPTION
 
@@ -38,6 +38,8 @@ find out the reason.
 
 The return value points to an allocated SSL structure.
 
+SSL_up_ref() returns 1 for success and 0 for failure.
+
 =back
 
 =head1 SEE ALSO
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 1ade6acda1..88198d1be7 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -271,7 +271,7 @@ protocol context defined in the B<SSL_CTX> structure.
 
 =item SSL_CTX *B<SSL_CTX_new>(const SSL_METHOD *meth);
 
-=item void SSL_CTX_up_ref(SSL_CTX *ctx);
+=item int SSL_CTX_up_ref(SSL_CTX *ctx);
 
 =item int B<SSL_CTX_remove_session>(SSL_CTX *ctx, SSL_SESSION *c);
 
@@ -599,7 +599,7 @@ fresh handle for each connection.
 
 =item SSL *B<SSL_new>(SSL_CTX *ctx);
 
-=item void SSL_up_ref(SSL *s);
+=item int SSL_up_ref(SSL *s);
 
 =item long B<SSL_num_renegotiations>(SSL *ssl);