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 0853ce588ce3900a80e6a46c0551271936310402..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,
-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
@@ -12,13 +13,13 @@ CRYPTO_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
  #include <openssl/crypto.h>
 
  int CRYPTO_get_ex_new_index(int class_index,
-                long argl, void *argp,
-                CRYPTO_EX_new *new_func,
-                CRYPTO_EX_dup *dup_func,
-                CRYPTO_EX_free *free_func);
+                             long argl, void *argp,
+                             CRYPTO_EX_new *new_func,
+                             CRYPTO_EX_dup *dup_func,
+                             CRYPTO_EX_free *free_func);
 
- typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
-                           int idx, long argl, void *argp);
+ typedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
+                            int idx, long argl, void *argp);
  typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
                              int idx, long argl, void *argp);
  typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
@@ -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_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);
@@ -40,20 +44,22 @@ Several OpenSSL structures can have application-specific data attached to them,
 known as "exdata."
 The specific structures are:
 
-    SSL
-    SSL_CTX
-    SSL_SESSION
-    X509
-    X509_STORE
-    X509_STORE_CTX
+    APP
+    BIO
     DH
+    DRBG
     DSA
     EC_KEY
-    RSA
     ENGINE
+    RSA
+    SSL
+    SSL_CTX
+    SSL_SESSION
     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
@@ -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
-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
@@ -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.
-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
@@ -128,7 +135,8 @@ initially registered via CRYPTO_get_ex_new_index() and can be used if
 the same callback handles different types of exdata.
 
 dup_func() is called when a structure is being copied.  This is only done
-for B<SSL> and B<SSL_SESSION> objects.  The B<to> and B<from> parameters
+for B<SSL>, B<SSL_SESSION>, B<EC_KEY> objects and B<BIO> chains via
+BIO_dup_chain().  The B<to> and B<from> parameters
 are pointers to the destination and source B<CRYPTO_EX_DATA> structures,
 respectively.  The B<from_d> parameter needs to be cast to a B<void **pptr>
 as the API has currently the wrong signature; that will be changed in a
@@ -142,22 +150,25 @@ will fail.
 
 =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.
 
+=head1 HISTORY
+
+CRYPTO_alloc_ex_data() was added in OpenSSL 3.0.0.
+
 =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>.