Update copyright year

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

diff --git a/doc/crypto/CRYPTO_get_ex_new_index.pod b/doc/crypto/CRYPTO_get_ex_new_index.pod
index f0e19b1eb195695ecab11becab4c679e085aac28..a5bf62097285e2d133922195b22802eb3c81a2e4 100644 (file)
--- a/doc/crypto/CRYPTO_get_ex_new_index.pod
+++ b/doc/crypto/CRYPTO_get_ex_new_index.pod
@@ -2,8 +2,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_get_ex_data, CRYPTO_free_ex_data, CRYPTO_new_ex_data
 - functions supporting application-specific data
 
 =head1 SYNOPSIS
@@ -16,13 +17,15 @@ CRYPTO_get_ex_data, CRYPTO_free_ex_data
                 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, CRYPTO_EX_DATA *from,
+ typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
                            void *from_d, int idx, long argl, void *argp);
 
+ int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
+
  int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
 
  void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
@@ -49,6 +52,7 @@ The specific structures are:
     RSA
     ENGINE
     UI
+    UI_METHOD
     BIO
 
 Each is identified by an B<CRYPTO_EX_INDEX_xxx> define in the B<crypto.h>
@@ -59,6 +63,10 @@ The API described here is used by OpenSSL to manipulate exdata for specific
 structures.  Since the application data can be anything at all it is passed
 and retrieved as a B<void *> type.
 
+The B<CRYPTO_EX_DATA> type is opaque.  To initialize the exdata part of
+a structure, call CRYPTO_new_ex_data(). This is only necessary for
+B<CRYPTO_EX_INDEX_APP> objects.
+
 Exdata types are identified by an B<index>, an integer guaranteed to be
 unique within structures for the lifetime of the program.  Applications
 using exdata typically call B<CRYPTO_get_ex_new_index> at startup, and
@@ -120,14 +128,18 @@ 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<srcp> parameter is a pointer to the source exdata.
-When the dup_func() returns, the value in B<srcp> is copied to the
-destination ex_data.  If the pointer contained in B<srcp> is not modified
+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
+future version.  The B<*pptr> is a pointer to the source exdata.
+When the dup_func() returns, the value in B<*pptr> is copied to the
+destination ex_data.  If the pointer contained in B<*pptr> is not modified
 by the dup_func(), then both B<to> and B<from> will point to the same data.
 The B<idx>, B<argl> and B<argp> parameters are as described for the other
-two callbacks.
+two callbacks.  If the dup_func() returns B<0> the whole CRYPTO_dup_ex_data()
+will fail.
 
 =head1 RETURN VALUES
 
@@ -144,7 +156,7 @@ dup_func() should return 0 for failure and 1 for success.
 
 =head1 COPYRIGHT
 
-Copyright 2015-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2015-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy