secure/lib/libcrypto/man/CRYPTO_get_ex_new_index.3

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