Document "get/set-app-data" macros.
[openssl.git] / doc / man3 / BIO_get_ex_new_index.pod
1 =pod
2
3 =head1 NAME
4
5 BIO_get_ex_new_index, BIO_set_ex_data, BIO_get_ex_data,
6 BIO_set_app_data, BIO_get_app_data,
7 DH_get_ex_new_index, DH_set_ex_data, DH_get_ex_data,
8 DSA_get_ex_new_index, DSA_set_ex_data, DSA_get_ex_data,
9 ECDH_get_ex_new_index, ECDH_set_ex_data, ECDH_get_ex_data,
10 EC_KEY_get_ex_new_index, EC_KEY_set_ex_data, EC_KEY_get_ex_data,
11 ENGINE_get_ex_new_index, ENGINE_set_ex_data, ENGINE_get_ex_data,
12 RAND_DRBG_set_ex_data, RAND_DRBG_get_ex_data, RAND_DRBG_get_ex_new_index,
13 RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data,
14 RSA_set_app_data, RSA_get_app_data,
15 SSL_get_ex_new_index, SSL_set_ex_data, SSL_get_ex_data,
16 SSL_set_app_data, SSL_get_app_data,
17 SSL_CTX_get_ex_new_index, SSL_CTX_set_ex_data, SSL_CTX_get_ex_data,
18 SSL_CTX_set_app_data, SSL_CTX_get_app_data,
19 SSL_SESSION_get_ex_new_index, SSL_SESSION_set_ex_data, SSL_SESSION_get_ex_data,
20 SSL_SESSION_set_app_data, SSL_SESSION_get_app_data,
21 UI_get_ex_new_index, UI_set_ex_data, UI_get_ex_data,
22 UI_set_app_data, UI_get_app_data,
23 X509_STORE_CTX_get_ex_new_index, X509_STORE_CTX_set_ex_data, X509_STORE_CTX_get_ex_data,
24 X509_STORE_CTX_set_app_data, X509_STORE_CTX_get_app_data,
25 X509_STORE_get_ex_new_index, X509_STORE_set_ex_data, X509_STORE_get_ex_data,
26 X509_get_ex_new_index, X509_set_ex_data, X509_get_ex_data
27 - application-specific data
28
29 =head1 SYNOPSIS
30
31 =for openssl generic
32
33  #include <openssl/x509.h>
34
35  int TYPE_get_ex_new_index(long argl, void *argp,
36                            CRYPTO_EX_new *new_func,
37                            CRYPTO_EX_dup *dup_func,
38                            CRYPTO_EX_free *free_func);
39
40  int TYPE_set_ex_data(TYPE *d, int idx, void *arg);
41
42  void *TYPE_get_ex_data(TYPE *d, int idx);
43
44  #define TYPE_set_app_data(TYPE *d, void *arg)
45  #define TYPE_get_app_data(TYPE *d)
46
47 =head1 DESCRIPTION
48
49 In the description here, I<TYPE> is used a placeholder
50 for any of the OpenSSL datatypes listed in
51 L<CRYPTO_get_ex_new_index(3)>.
52
53 These functions handle application-specific data for OpenSSL data
54 structures.
55
56 TYPE_get_new_ex_index() is a macro that calls CRYPTO_get_ex_new_index()
57 with the correct B<index> value.
58
59 TYPE_set_ex_data() is a function that calls CRYPTO_set_ex_data() with
60 an offset into the opaque exdata part of the TYPE object.
61
62 TYPE_get_ex_data() is a function that calls CRYPTO_get_ex_data() with
63 an offset into the opaque exdata part of the TYPE object.
64
65 For compatibility with previous releases, the exdata index of zero is
66 reserved for "application data." There are two convenience functions for
67 this.
68 TYPE_set_app_data() is a macro that invokes TYPE_set_ex_data() with
69 B<idx> set to zero.
70 TYPE_get_app_data() is a macro that invokes TYPE_get_ex_data() with
71 B<idx> set to zero.
72 Note that these functions are not defined for the B<RAND_DRBG> type because
73 there are no backward compatibility concerns.
74
75 =head1 RETURN VALUES
76
77 TYPE_get_new_ex_index() returns a new index on success or -1 on error.
78
79 TYPE_set_ex_data() returns 1 on success or 0 on error.
80
81 TYPE_get_ex_data() returns the application data or NULL if an error occurred.
82
83 =head1 SEE ALSO
84
85 L<CRYPTO_get_ex_new_index(3)>.
86
87 =head1 COPYRIGHT
88
89 Copyright 2015-2018 The OpenSSL Project Authors. All Rights Reserved.
90
91 Licensed under the Apache License 2.0 (the "License").  You may not use
92 this file except in compliance with the License.  You can obtain a copy
93 in the file LICENSE in the source distribution or at
94 L<https://www.openssl.org/source/license.html>.
95
96 =cut