Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / RSA_get_ex_new_index.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
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-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
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' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
8b0cefbb 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
8b0cefbb 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
8b0cefbb
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
8b0cefbb
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
8b0cefbb
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
8b0cefbb
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
8b0cefbb
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
8b0cefbb 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
8b0cefbb
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
8b0cefbb
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
8b0cefbb 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
8b0cefbb
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
8b0cefbb
JR
124.\" ========================================================================
125.\"
126.IX Title "RSA_get_ex_new_index 3"
e3261593 127.TH RSA_get_ex_new_index 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc 132.SH "NAME"
74dab6c2 133RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data \- add application specific data to RSA structures
984263bc 134.SH "SYNOPSIS"
8b0cefbb 135.IX Header "SYNOPSIS"
984263bc
MD
136.Vb 1
137\& #include <openssl/rsa.h>
e257b235 138\&
984263bc
MD
139\& int RSA_get_ex_new_index(long argl, void *argp,
140\& CRYPTO_EX_new *new_func,
141\& CRYPTO_EX_dup *dup_func,
142\& CRYPTO_EX_free *free_func);
e257b235 143\&
984263bc 144\& int RSA_set_ex_data(RSA *r, int idx, void *arg);
e257b235 145\&
984263bc 146\& void *RSA_get_ex_data(RSA *r, int idx);
e257b235 147\&
edae4a78
PA
148\& typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
149\& int idx, long argl, void *argp);
150\& typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
151\& int idx, long argl, void *argp);
152\& typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
153\& int idx, long argl, void *argp);
984263bc
MD
154.Ve
155.SH "DESCRIPTION"
8b0cefbb 156.IX Header "DESCRIPTION"
984263bc
MD
157Several OpenSSL structures can have application specific data attached to them.
158This has several potential uses, it can be used to cache data associated with
159a structure (for example the hash of some part of the structure) or some
160additional data (for example a handle to the data in an external library).
161.PP
162Since the application data can be anything at all it is passed and retrieved
163as a \fBvoid *\fR type.
164.PP
8b0cefbb 165The \fB\f(BIRSA_get_ex_new_index()\fB\fR function is initially called to \*(L"register\*(R" some
984263bc 166new application specific data. It takes three optional function pointers which
8b0cefbb 167are called when the parent structure (in this case an \s-1RSA\s0 structure) is
984263bc 168initially created, when it is copied and when it is freed up. If any or all of
8b0cefbb 169these function pointer arguments are not used they should be set to \s-1NULL\s0. The
984263bc 170precise manner in which these function pointers are called is described in more
8b0cefbb 171detail below. \fB\f(BIRSA_get_ex_new_index()\fB\fR also takes additional long and pointer
984263bc
MD
172parameters which will be passed to the supplied functions but which otherwise
173have no special meaning. It returns an \fBindex\fR which should be stored
174(typically in a static variable) and passed used in the \fBidx\fR parameter in
8b0cefbb 175the remaining functions. Each successful call to \fB\f(BIRSA_get_ex_new_index()\fB\fR
984263bc
MD
176will return an index greater than any previously returned, this is important
177because the optional functions are called in order of increasing index value.
178.PP
8b0cefbb 179\&\fB\f(BIRSA_set_ex_data()\fB\fR is used to set application specific data, the data is
984263bc
MD
180supplied in the \fBarg\fR parameter and its precise meaning is up to the
181application.
182.PP
8b0cefbb 183\&\fB\f(BIRSA_get_ex_data()\fB\fR is used to retrieve application specific data. The data
984263bc 184is returned to the application, this will be the same value as supplied to
8b0cefbb 185a previous \fB\f(BIRSA_set_ex_data()\fB\fR call.
984263bc 186.PP
8b0cefbb
JR
187\&\fB\f(BInew_func()\fB\fR is called when a structure is initially allocated (for example
188with \fB\f(BIRSA_new()\fB\fR. The parent structure members will not have any meaningful
984263bc
MD
189values at this point. This function will typically be used to allocate any
190application specific structure.
191.PP
8b0cefbb 192\&\fB\f(BIfree_func()\fB\fR is called when a structure is being freed up. The dynamic parent
984263bc
MD
193structure members should not be accessed because they will be freed up when
194this function is called.
195.PP
8b0cefbb
JR
196\&\fB\f(BInew_func()\fB\fR and \fB\f(BIfree_func()\fB\fR take the same parameters. \fBparent\fR is a
197pointer to the parent \s-1RSA\s0 structure. \fBptr\fR is a the application specific data
198(this wont be of much use in \fB\f(BInew_func()\fB\fR. \fBad\fR is a pointer to the
199\&\fB\s-1CRYPTO_EX_DATA\s0\fR structure from the parent \s-1RSA\s0 structure: the functions
200\&\fB\f(BICRYPTO_get_ex_data()\fB\fR and \fB\f(BICRYPTO_set_ex_data()\fB\fR can be called to manipulate
984263bc 201it. The \fBidx\fR parameter is the index: this will be the same value returned by
8b0cefbb 202\&\fB\f(BIRSA_get_ex_new_index()\fB\fR when the functions were initially registered. Finally
984263bc 203the \fBargl\fR and \fBargp\fR parameters are the values originally passed to the same
8b0cefbb 204corresponding parameters when \fB\f(BIRSA_get_ex_new_index()\fB\fR was called.
984263bc 205.PP
8b0cefbb
JR
206\&\fB\f(BIdup_func()\fB\fR is called when a structure is being copied. Pointers to the
207destination and source \fB\s-1CRYPTO_EX_DATA\s0\fR structures are passed in the \fBto\fR and
208\&\fBfrom\fR parameters respectively. The \fBfrom_d\fR parameter is passed a pointer to
984263bc
MD
209the source application data when the function is called, when the function returns
210the value is copied to the destination: the application can thus modify the data
211pointed to by \fBfrom_d\fR and have different values in the source and destination.
8b0cefbb
JR
212The \fBidx\fR, \fBargl\fR and \fBargp\fR parameters are the same as those in \fB\f(BInew_func()\fB\fR
213and \fB\f(BIfree_func()\fB\fR.
984263bc 214.SH "RETURN VALUES"
8b0cefbb
JR
215.IX Header "RETURN VALUES"
216\&\fB\f(BIRSA_get_ex_new_index()\fB\fR returns a new index or \-1 on failure (note 0 is a valid
984263bc
MD
217index value).
218.PP
8b0cefbb 219\&\fB\f(BIRSA_set_ex_data()\fB\fR returns 1 on success or 0 on failure.
984263bc 220.PP
8b0cefbb 221\&\fB\f(BIRSA_get_ex_data()\fB\fR returns the application data or 0 on failure. 0 may also
984263bc
MD
222be valid application data but currently it can only fail if given an invalid \fBidx\fR
223parameter.
224.PP
8b0cefbb 225\&\fB\f(BInew_func()\fB\fR and \fB\f(BIdup_func()\fB\fR should return 0 for failure and 1 for success.
984263bc 226.PP
8b0cefbb 227On failure an error code can be obtained from \fIERR_get_error\fR\|(3).
984263bc 228.SH "BUGS"
8b0cefbb
JR
229.IX Header "BUGS"
230\&\fB\f(BIdup_func()\fB\fR is currently never called.
984263bc 231.PP
8b0cefbb 232The return value of \fB\f(BInew_func()\fB\fR is ignored.
984263bc 233.PP
8b0cefbb
JR
234The \fB\f(BInew_func()\fB\fR function isn't very useful because no meaningful values are
235present in the parent \s-1RSA\s0 structure when it is called.
984263bc 236.SH "SEE ALSO"
74dab6c2 237.IX Header "SEE ALSO"
8b0cefbb
JR
238\&\fIrsa\fR\|(3), \fICRYPTO_set_ex_data\fR\|(3)
239.SH "HISTORY"
74dab6c2 240.IX Header "HISTORY"
8b0cefbb
JR
241\&\fIRSA_get_ex_new_index()\fR, \fIRSA_set_ex_data()\fR and \fIRSA_get_ex_data()\fR are
242available since SSLeay 0.9.0.