Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / RSA_get_ex_new_index.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
34'''
35'''
36''' Set up \*(-- to give an unbreakable dash;
37''' string Tr holds user defined translation string.
38''' Bell System Logo is used as a dummy character.
39'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
42.ds -- \(*W-
43.ds PI pi
44.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
46.ds L" ""
47.ds R" ""
48''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of
49''' \*(L" and \*(R", except that they are used on ".xx" lines,
50''' such as .IP and .SH, which do another additional levels of
51''' double-quote interpretation
52.ds M" """
53.ds S" """
54.ds N" """""
55.ds T" """""
56.ds L' '
57.ds R' '
58.ds M' '
59.ds S' '
60.ds N' '
61.ds T' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
64.ds -- \(em\|
65.tr \*(Tr
66.ds L" ``
67.ds R" ''
68.ds M" ``
69.ds S" ''
70.ds N" ``
71.ds T" ''
72.ds L' `
73.ds R' '
74.ds M' `
75.ds S' '
76.ds N' `
77.ds T' '
78.ds PI \(*p
984263bc 79'br\}
74dab6c2
JR
80.\" If the F register is turned on, we'll generate
81.\" index entries out stderr for the following things:
82.\" TH Title
83.\" SH Header
84.\" Sh Subsection
85.\" Ip Item
86.\" X<> Xref (embedded
87.\" Of course, you have to process the output yourself
88.\" in some meaninful fashion.
89.if \nF \{
90.de IX
91.tm Index:\\$1\t\\n%\t"\\$2"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH RSA_get_ex_new_index 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
100.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
101.de CQ \" put $1 in typewriter font
102.ft CW
103'if n "\c
104'if t \\&\\$1\c
105'if n \\&\\$1\c
106'if n \&"
107\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
108'.ft R
109..
110.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
111. \" AM - accent mark definitions
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
141. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
142. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
143. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
144. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
145. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
146. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
147. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
148. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
149. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
152.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
153.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
74dab6c2
JR
154.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
155.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
156.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
157.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
984263bc
MD
158.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
159.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
160.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
161.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
162.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
163.ds ae a\h'-(\w'a'u*4/10)'e
164.ds Ae A\h'-(\w'A'u*4/10)'E
74dab6c2
JR
165.ds oe o\h'-(\w'o'u*4/10)'e
166.ds Oe O\h'-(\w'O'u*4/10)'E
167. \" corrections for vroff
984263bc
MD
168.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
169.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
173. ds : e
174. ds 8 ss
175. ds v \h'-1'\o'\(aa\(ga'
176. ds _ \h'-1'^
177. ds . \h'-1'.
178. ds 3 3
179. ds o a
180. ds d- d\h'-1'\(ga
181. ds D- D\h'-1'\(hy
182. ds th \o'bp'
183. ds Th \o'LP'
184. ds ae ae
185. ds Ae AE
186. ds oe oe
187. ds Oe OE
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc 190.SH "NAME"
74dab6c2 191RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data \- add application specific data to RSA structures
984263bc 192.SH "SYNOPSIS"
74dab6c2 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/rsa.h>
196.Ve
197.Vb 4
198\& int RSA_get_ex_new_index(long argl, void *argp,
199\& CRYPTO_EX_new *new_func,
200\& CRYPTO_EX_dup *dup_func,
201\& CRYPTO_EX_free *free_func);
202.Ve
203.Vb 1
204\& int RSA_set_ex_data(RSA *r, int idx, void *arg);
205.Ve
206.Vb 1
207\& void *RSA_get_ex_data(RSA *r, int idx);
208.Ve
209.Vb 6
210\& typedef int new_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
211\& int idx, long argl, void *argp);
212\& typedef void free_func(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
213\& int idx, long argl, void *argp);
214\& typedef int dup_func(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
215\& int idx, long argl, void *argp);
216.Ve
217.SH "DESCRIPTION"
984263bc
MD
218Several OpenSSL structures can have application specific data attached to them.
219This has several potential uses, it can be used to cache data associated with
220a structure (for example the hash of some part of the structure) or some
221additional data (for example a handle to the data in an external library).
222.PP
223Since the application data can be anything at all it is passed and retrieved
224as a \fBvoid *\fR type.
225.PP
74dab6c2 226The \fBRSA_get_ex_new_index()\fR function is initially called to \*(L"register\*(R" some
984263bc 227new application specific data. It takes three optional function pointers which
74dab6c2 228are called when the parent structure (in this case an RSA structure) is
984263bc 229initially created, when it is copied and when it is freed up. If any or all of
74dab6c2 230these function pointer arguments are not used they should be set to NULL. The
984263bc 231precise manner in which these function pointers are called is described in more
74dab6c2 232detail below. \fBRSA_get_ex_new_index()\fR also takes additional long and pointer
984263bc
MD
233parameters which will be passed to the supplied functions but which otherwise
234have no special meaning. It returns an \fBindex\fR which should be stored
235(typically in a static variable) and passed used in the \fBidx\fR parameter in
74dab6c2 236the remaining functions. Each successful call to \fBRSA_get_ex_new_index()\fR
984263bc
MD
237will return an index greater than any previously returned, this is important
238because the optional functions are called in order of increasing index value.
239.PP
74dab6c2 240\fBRSA_set_ex_data()\fR is used to set application specific data, the data is
984263bc
MD
241supplied in the \fBarg\fR parameter and its precise meaning is up to the
242application.
243.PP
74dab6c2 244\fBRSA_get_ex_data()\fR is used to retrieve application specific data. The data
984263bc 245is returned to the application, this will be the same value as supplied to
74dab6c2 246a previous \fBRSA_set_ex_data()\fR call.
984263bc 247.PP
74dab6c2
JR
248\fBnew_func()\fR is called when a structure is initially allocated (for example
249with \fBRSA_new()\fR. The parent structure members will not have any meaningful
984263bc
MD
250values at this point. This function will typically be used to allocate any
251application specific structure.
252.PP
74dab6c2 253\fBfree_func()\fR is called when a structure is being freed up. The dynamic parent
984263bc
MD
254structure members should not be accessed because they will be freed up when
255this function is called.
256.PP
74dab6c2
JR
257\fBnew_func()\fR and \fBfree_func()\fR take the same parameters. \fBparent\fR is a
258pointer to the parent RSA structure. \fBptr\fR is a the application specific data
259(this wont be of much use in \fBnew_func()\fR. \fBad\fR is a pointer to the
260\fBCRYPTO_EX_DATA\fR structure from the parent RSA structure: the functions
261\fBCRYPTO_get_ex_data()\fR and \fBCRYPTO_set_ex_data()\fR can be called to manipulate
984263bc 262it. The \fBidx\fR parameter is the index: this will be the same value returned by
74dab6c2 263\fBRSA_get_ex_new_index()\fR when the functions were initially registered. Finally
984263bc 264the \fBargl\fR and \fBargp\fR parameters are the values originally passed to the same
74dab6c2 265corresponding parameters when \fBRSA_get_ex_new_index()\fR was called.
984263bc 266.PP
74dab6c2
JR
267\fBdup_func()\fR is called when a structure is being copied. Pointers to the
268destination and source \fBCRYPTO_EX_DATA\fR structures are passed in the \fBto\fR and
269\fBfrom\fR parameters respectively. The \fBfrom_d\fR parameter is passed a pointer to
984263bc
MD
270the source application data when the function is called, when the function returns
271the value is copied to the destination: the application can thus modify the data
272pointed to by \fBfrom_d\fR and have different values in the source and destination.
74dab6c2
JR
273The \fBidx\fR, \fBargl\fR and \fBargp\fR parameters are the same as those in \fBnew_func()\fR
274and \fBfree_func()\fR.
984263bc 275.SH "RETURN VALUES"
74dab6c2 276\fBRSA_get_ex_new_index()\fR returns a new index or \-1 on failure (note 0 is a valid
984263bc
MD
277index value).
278.PP
74dab6c2 279\fBRSA_set_ex_data()\fR returns 1 on success or 0 on failure.
984263bc 280.PP
74dab6c2 281\fBRSA_get_ex_data()\fR returns the application data or 0 on failure. 0 may also
984263bc
MD
282be valid application data but currently it can only fail if given an invalid \fBidx\fR
283parameter.
284.PP
74dab6c2 285\fBnew_func()\fR and \fBdup_func()\fR should return 0 for failure and 1 for success.
984263bc
MD
286.PP
287On failure an error code can be obtained from ERR_get_error(3).
288.SH "BUGS"
74dab6c2 289\fBdup_func()\fR is currently never called.
984263bc 290.PP
74dab6c2 291The return value of \fBnew_func()\fR is ignored.
984263bc 292.PP
74dab6c2
JR
293The \fBnew_func()\fR function isn't very useful because no meaningful values are
294present in the parent RSA structure when it is called.
984263bc 295.SH "SEE ALSO"
984263bc
MD
296rsa(3), CRYPTO_set_ex_data(3)
297.SH "HISTORY"
74dab6c2 298\fIRSA_get_ex_new_index()\fR, \fIRSA_set_ex_data()\fR and \fIRSA_get_ex_data()\fR are
984263bc 299available since SSLeay 0.9.0.
74dab6c2
JR
300
301.rn }` ''
302.IX Title "RSA_get_ex_new_index 3"
303.IX Name "RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data - add application specific data to RSA structures"
304
305.IX Header "NAME"
306
307.IX Header "SYNOPSIS"
308
309.IX Header "DESCRIPTION"
310
311.IX Header "RETURN VALUES"
312
313.IX Header "BUGS"
314
315.IX Header "SEE ALSO"
316
317.IX Header "HISTORY"
318