secure/lib/libcrypto/man/CRYPTO_get_ex_new_index.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "CRYPTO_GET_EX_NEW_INDEX 3"
 132 .TH CRYPTO_GET_EX_NEW_INDEX 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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 \&\- functions supporting application\-specific data
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/crypto.h>
 143 \&
 144 \& int CRYPTO_get_ex_new_index(int class_index,
 145 \&                             long argl, void *argp,
 146 \&                             CRYPTO_EX_new *new_func,
 147 \&                             CRYPTO_EX_dup *dup_func,
 148 \&                             CRYPTO_EX_free *free_func);
 149 \&
 150 \& typedef void CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
 151 \&                            int idx, long argl, void *argp);
 152 \& typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
 153 \&                             int idx, long argl, void *argp);
 154 \& typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, const CRYPTO_EX_DATA *from,
 155 \&                           void *from_d, int idx, long argl, void *argp);
 156 \&
 157 \& int CRYPTO_new_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *ad)
 158 \&
 159 \& int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
 160 \&
 161 \& void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
 162 \&
 163 \& void CRYPTO_free_ex_data(int class_index, void *obj, CRYPTO_EX_DATA *r);
 164 \&
 165 \& int CRYPTO_free_ex_index(int class_index, int idx);
 166 .Ve
 167 .SH "DESCRIPTION"
 168 .IX Header "DESCRIPTION"
 169 Several OpenSSL structures can have application-specific data attached to them,
 170 known as \*(L"exdata.\*(R"
 171 The specific structures are:
 172 .PP
 173 .Vb 10
 174 \&    APP
 175 \&    BIO
 176 \&    DH
 177 \&    DRBG
 178 \&    DSA
 179 \&    EC_KEY
 180 \&    ENGINE
 181 \&    RSA
 182 \&    SSL
 183 \&    SSL_CTX
 184 \&    SSL_SESSION
 185 \&    UI
 186 \&    UI_METHOD
 187 \&    X509
 188 \&    X509_STORE
 189 \&    X509_STORE_CTX
 190 .Ve
 191 .PP
 192 Each is identified by an \fBCRYPTO_EX_INDEX_xxx\fR define in the \fBcrypto.h\fR
 193 header file.  In addition, \fB\s-1CRYPTO_EX_INDEX_APP\s0\fR is reserved for
 194 applications to use this facility for their own structures.
 195 .PP
 196 The \s-1API\s0 described here is used by OpenSSL to manipulate exdata for specific
 197 structures.  Since the application data can be anything at all it is passed
 198 and retrieved as a \fBvoid *\fR type.
 199 .PP
 200 The \fB\s-1CRYPTO_EX_DATA\s0\fR type is opaque.  To initialize the exdata part of
 201 a structure, call \fICRYPTO_new_ex_data()\fR. This is only necessary for
 202 \&\fB\s-1CRYPTO_EX_INDEX_APP\s0\fR objects.
 203 .PP
 204 Exdata types are identified by an \fBindex\fR, an integer guaranteed to be
 205 unique within structures for the lifetime of the program.  Applications
 206 using exdata typically call \fBCRYPTO_get_ex_new_index\fR at startup, and
 207 store the result in a global variable, or write a wrapper function to
 208 provide lazy evaluation.  The \fBclass_index\fR should be one of the
 209 \&\fBCRYPTO_EX_INDEX_xxx\fR values. The \fBargl\fR and \fBargp\fR parameters are saved
 210 to be passed to the callbacks but are otherwise not used.  In order to
 211 transparently manipulate exdata, three callbacks must be provided. The
 212 semantics of those callbacks are described below.
 213 .PP
 214 When copying or releasing objects with exdata, the callback functions
 215 are called in increasing order of their \fBindex\fR value.
 216 .PP
 217 If a dynamic library can be unloaded, it should call \fICRYPTO_free_ex_index()\fR
 218 when this is done.
 219 This will replace the callbacks with no-ops
 220 so that applications don't crash.  Any existing exdata will be leaked.
 221 .PP
 222 To set or get the exdata on an object, the appropriate type-specific
 223 routine must be used.  This is because the containing structure is opaque
 224 and the \fB\s-1CRYPTO_EX_DATA\s0\fR field is not accessible.  In both \s-1API\s0's, the
 225 \&\fBidx\fR parameter should be an already-created index value.
 226 .PP
 227 When setting exdata, the pointer specified with a particular index is saved,
 228 and returned on a subsequent \*(L"get\*(R" call.  If the application is going to
 229 release the data, it must make sure to set a \fB\s-1NULL\s0\fR value at the index,
 230 to avoid likely double-free crashes.
 231 .PP
 232 The function \fBCRYPTO_free_ex_data\fR is used to free all exdata attached
 233 to a structure. The appropriate type-specific routine must be used.
 234 The \fBclass_index\fR identifies the structure type, the \fBobj\fR is
 235 be the pointer to the actual structure, and \fBr\fR is a pointer to the
 236 structure's exdata field.
 237 .SS "Callback Functions"
 238 .IX Subsection "Callback Functions"
 239 This section describes how the callback functions are used. Applications
 240 that are defining their own exdata using \fB\s-1CYPRTO_EX_INDEX_APP\s0\fR must
 241 call them as described here.
 242 .PP
 243 When a structure is initially allocated (such as \fIRSA_new()\fR) then the
 244 \&\fInew_func()\fR is called for every defined index. There is no requirement
 245 that the entire parent, or containing, structure has been set up.
 246 The \fInew_func()\fR is typically used only to allocate memory to store the
 247 exdata, and perhaps an \*(L"initialized\*(R" flag within that memory.
 248 The exdata value should be set by calling \fICRYPTO_set_ex_data()\fR.
 249 .PP
 250 When a structure is free'd (such as \fISSL_CTX_free()\fR) then the
 251 \&\fIfree_func()\fR is called for every defined index.  Again, the state of the
 252 parent structure is not guaranteed.  The \fIfree_func()\fR may be called with a
 253 \&\s-1NULL\s0 pointer.
 254 .PP
 255 Both \fInew_func()\fR and \fIfree_func()\fR take the same parameters.
 256 The \fBparent\fR is the pointer to the structure that contains the exdata.
 257 The \fBptr\fR is the current exdata item; for \fInew_func()\fR this will typically
 258 be \s-1NULL.\s0  The \fBr\fR parameter is a pointer to the exdata field of the object.
 259 The \fBidx\fR is the index and is the value returned when the callbacks were
 260 initially registered via \fICRYPTO_get_ex_new_index()\fR and can be used if
 261 the same callback handles different types of exdata.
 262 .PP
 263 \&\fIdup_func()\fR is called when a structure is being copied.  This is only done
 264 for \fB\s-1SSL\s0\fR, \fB\s-1SSL_SESSION\s0\fR, \fB\s-1EC_KEY\s0\fR objects and \fB\s-1BIO\s0\fR chains via
 265 \&\fIBIO_dup_chain()\fR.  The \fBto\fR and \fBfrom\fR parameters
 266 are pointers to the destination and source \fB\s-1CRYPTO_EX_DATA\s0\fR structures,
 267 respectively.  The \fBfrom_d\fR parameter needs to be cast to a \fBvoid **pptr\fR
 268 as the \s-1API\s0 has currently the wrong signature; that will be changed in a
 269 future version.  The \fB*pptr\fR is a pointer to the source exdata.
 270 When the \fIdup_func()\fR returns, the value in \fB*pptr\fR is copied to the
 271 destination ex_data.  If the pointer contained in \fB*pptr\fR is not modified
 272 by the \fIdup_func()\fR, then both \fBto\fR and \fBfrom\fR will point to the same data.
 273 The \fBidx\fR, \fBargl\fR and \fBargp\fR parameters are as described for the other
 274 two callbacks.  If the \fIdup_func()\fR returns \fB0\fR the whole \fICRYPTO_dup_ex_data()\fR
 275 will fail.
 276 .SH "RETURN VALUES"
 277 .IX Header "RETURN VALUES"
 278 \&\fICRYPTO_get_ex_new_index()\fR returns a new index or \-1 on failure.
 279 .PP
 280 \&\fICRYPTO_free_ex_index()\fR and
 281 \&\fICRYPTO_set_ex_data()\fR return 1 on success or 0 on failure.
 282 .PP
 283 \&\fICRYPTO_get_ex_data()\fR returns the application data or \s-1NULL\s0 on failure;
 284 note that \s-1NULL\s0 may be a valid value.
 285 .PP
 286 \&\fIdup_func()\fR should return 0 for failure and 1 for success.
 287 .SH "COPYRIGHT"
 288 .IX Header "COPYRIGHT"
 289 Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
 290 .PP
 291 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 292 this file except in compliance with the License.  You can obtain a copy
 293 in the file \s-1LICENSE\s0 in the source distribution or at
 294 <https://www.openssl.org/source/license.html>.