Fix a grammar nit in CRYPTO_get_ex_new_index.pod

[openssl.git] / doc / man3 / CRYPTO_get_ex_new_index.pod

diff --git a/doc/man3/CRYPTO_get_ex_new_index.pod b/doc/man3/CRYPTO_get_ex_new_index.pod
index 8251dda94f3e9c5b781cad81e67c5a7a1e9186ed..f37d532b98de984fb09150b688a9c32413e163ca 100644 (file)
--- a/doc/man3/CRYPTO_get_ex_new_index.pod
+++ b/doc/man3/CRYPTO_get_ex_new_index.pod
@@ -3,8 +3,9 @@
 =head1 NAME
 
 CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup,
 =head1 NAME
 
 CRYPTO_EX_new, CRYPTO_EX_free, CRYPTO_EX_dup,

-CRYPTO_free_ex_index, CRYPTO_get_ex_new_index, CRYPTO_set_ex_data,
-CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
+CRYPTO_free_ex_index, CRYPTO_get_ex_new_index,
+CRYPTO_alloc_ex_data, CRYPTO_set_ex_data, CRYPTO_get_ex_data,
+CRYPTO_free_ex_data, CRYPTO_new_ex_data

 - functions supporting application-specific data
 
 =head1 SYNOPSIS
 - functions supporting application-specific data
 
 =head1 SYNOPSIS


@@ -26,6 +27,9 @@ CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
 
  int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
 
 
  int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
 

+ int CRYPTO_alloc_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad,
+                          int idx);
+

  int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
 
  void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
  int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
 
  void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);


@@ -40,20 +44,22 @@ Several OpenSSL structures can have application-specific data attached to them,
 known as "exdata."
 The specific structures are:
 
 known as "exdata."
 The specific structures are:
 

-    SSL
-    SSL_CTX
-    SSL_SESSION
-    X509
-    X509_STORE
-    X509_STORE_CTX
+    APP
+    BIO

     DH
     DH

+    DRBG

     DSA
     EC_KEY
     DSA
     EC_KEY

-    RSA

     ENGINE
     ENGINE

+    RSA
+    SSL
+    SSL_CTX
+    SSL_SESSION

     UI
     UI_METHOD
     UI
     UI_METHOD

-    BIO
+    X509
+    X509_STORE
+    X509_STORE_CTX

 
 Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h>
 header file.  In addition, B<CRYPTO_EX_INDEX_APP> is reserved for
 
 Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h>
 header file.  In addition, B<CRYPTO_EX_INDEX_APP> is reserved for


@@ -98,7 +104,7 @@ to avoid likely double-free crashes.
 The function B<CRYPTO_free_ex_data> is used to free all exdata attached
 to a structure. The appropriate type-specific routine must be used.
 The B<class_index> identifies the structure type, the B<obj> is
 The function B<CRYPTO_free_ex_data> is used to free all exdata attached
 to a structure. The appropriate type-specific routine must be used.
 The B<class_index> identifies the structure type, the B<obj> is

-be the pointer to the actual structure, and B<r> is a pointer to the
+a pointer to the actual structure, and B<r> is a pointer to the

 structure's exdata field.
 
 =head2 Callback Functions
 structure's exdata field.
 
 =head2 Callback Functions


@@ -112,7 +118,8 @@ new_func() is called for every defined index. There is no requirement
 that the entire parent, or containing, structure has been set up.
 The new_func() is typically used only to allocate memory to store the
 exdata, and perhaps an "initialized" flag within that memory.
 that the entire parent, or containing, structure has been set up.
 The new_func() is typically used only to allocate memory to store the
 exdata, and perhaps an "initialized" flag within that memory.

-The exdata value should be set by calling CRYPTO_set_ex_data().
+The exdata value may be allocated later on with CRYPTO_alloc_ex_data(),
+or may be set by calling CRYPTO_set_ex_data().

 
 When a structure is free'd (such as SSL_CTX_free()) then the
 free_func() is called for every defined index.  Again, the state of the
 
 When a structure is free'd (such as SSL_CTX_free()) then the
 free_func() is called for every defined index.  Again, the state of the


@@ -143,22 +150,25 @@ will fail.
 
 =head1 RETURN VALUES
 
 
 =head1 RETURN VALUES
 

-CRYPTO_get_ex_new_index() returns a new index or -1 on failure; the
-value B<0> is reserved for the legacy "app_data" API's.
+CRYPTO_get_ex_new_index() returns a new index or -1 on failure.

 
 

-CRYPTO_free_ex_index() and
-CRYPTO_set_ex_data() return 1 on success or 0 on failure.
+CRYPTO_free_ex_index(), CRYPTO_alloc_ex_data() and CRYPTO_set_ex_data()
+return 1 on success or 0 on failure. 

 
 CRYPTO_get_ex_data() returns the application data or NULL on failure;
 note that NULL may be a valid value.
 
 dup_func() should return 0 for failure and 1 for success.
 
 
 CRYPTO_get_ex_data() returns the application data or NULL on failure;
 note that NULL may be a valid value.
 
 dup_func() should return 0 for failure and 1 for success.
 

+=head1 HISTORY
+
+CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.0.
+

 =head1 COPYRIGHT
 
 =head1 COPYRIGHT
 

-Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.

 
 

-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use

 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.