Misc fix ups to deprecate explicit de-init documentation

[openssl.git] / doc / crypto / OBJ_nid2obj.pod

diff --git a/doc/crypto/OBJ_nid2obj.pod b/doc/crypto/OBJ_nid2obj.pod
index 7dcc07923ff91c46941f80fc9ff5ff26def60f71..d777d7ca5303d8fb7cf29049cec4f43c0f6556eb 100644 (file)
--- a/doc/crypto/OBJ_nid2obj.pod
+++ b/doc/crypto/OBJ_nid2obj.pod
@@ -8,6 +8,8 @@ functions
 
 =head1 SYNOPSIS
 
+ #include <openssl/objects.h>
+
  ASN1_OBJECT * OBJ_nid2obj(int n);
  const char *  OBJ_nid2ln(int n);
  const char *  OBJ_nid2sn(int n);
@@ -25,7 +27,15 @@ functions
  ASN1_OBJECT * OBJ_dup(const ASN1_OBJECT *o);
 
  int OBJ_create(const char *oid,const char *sn,const char *ln);
- void OBJ_cleanup(void);
+
+ size_t OBJ_length(const ASN1_OBJECT *obj);
+ const unsigned char *OBJ_get0_data(const ASN1_OBJECT *obj);
+
+Deprecated:
+
+ #if OPENSSL_API_COMPAT < 0x10100000L
+ void OBJ_cleanup(void)
+ #endif
 
 =head1 DESCRIPTION
 
@@ -41,7 +51,7 @@ for the object B<o>, the long name <ln> or the short name <sn> respectively
 or NID_undef if an error occurred.
 
 OBJ_txt2nid() returns NID corresponding to text string <s>. B<s> can be
-a long name, a short name or the numerical respresentation of an object.
+a long name, a short name or the numerical representation of an object.
 
 OBJ_txt2obj() converts the text string B<s> into an ASN1_OBJECT structure.
 If B<no_name> is 0 then long names and short names will be interpreted
@@ -64,9 +74,16 @@ OBJ_create() adds a new object to the internal table. B<oid> is the
 numerical form of the object, B<sn> the short name and B<ln> the
 long name. A new NID is returned for the created object.
 
-OBJ_cleanup() cleans up OpenSSLs internal object table: this should
-be called before an application exits if any new objects were added
-using OBJ_create().
+OBJ_length() returns the size of the content octets of B<obj>.
+
+OBJ_get0_data() returns a pointer to the content octets of B<obj>.
+The returned pointer is an internal pointer which B<must not> be freed.
+
+In OpenSSL versions prior to 1.1.0 OBJ_cleanup() cleaned up OpenSSLs internal
+object table and was called before an application exits if any new objects were
+added using OBJ_create(). This function is deprecated in version 1.1.0 and now
+does nothing if called. No explicit de-initialisation is now required. See
+L<OPENSSL_init_crypto(3)> for further information.
 
 =head1 NOTES
 
@@ -94,6 +111,12 @@ Objects do not need to be in the internal tables to be processed,
 the functions OBJ_txt2obj() and OBJ_obj2txt() can process the numerical
 form of an OID.
 
+Some objects are used to represent algorithms which do not have a
+corresponding ASN.1 OBJECT IDENTIFIER encoding (for example no OID currently
+exists for a particular algorithm). As a result they B<cannot> be encoded or
+decoded as part of ASN.1 structures. Applications can determine if there
+is a corresponding OBJECT IDENTIFIER by checking OBJ_length() is not zero.
+
 =head1 EXAMPLES
 
 Create an object for B<commonName>:
@@ -140,10 +163,10 @@ a NID or B<NID_undef> on error.
 
 =head1 SEE ALSO
 
-L<ERR_get_error(3)|ERR_get_error(3)>
+L<ERR_get_error(3)>
 
 =head1 HISTORY
 
-TBA
+OBJ_cleanup() was deprecated in OpenSSL 1.1.0.
 
 =cut