Upgrade to OpenSSL 0.9.8h.
[dragonfly.git] / secure / lib / libcrypto / man / RSA_get_ex_new_index.3
CommitLineData
aac4ff6f 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
5.de Sh \" Subsection heading
984263bc
MD
6.br
7.if t .Sp
8.ne 5
9.PP
10\fB\\$1\fR
11.PP
12..
8b0cefbb 13.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
14.if t .sp .5v
15.if n .sp
16..
8b0cefbb 17.de Vb \" Begin verbatim text
984263bc
MD
18.ft CW
19.nf
20.ne \\$1
21..
8b0cefbb 22.de Ve \" End verbatim text
984263bc 23.ft R
984263bc
MD
24.fi
25..
8b0cefbb
JR
26.\" Set up some character translations and predefined strings. \*(-- will
27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
aac4ff6f
PA
28.\" double quote, and \*(R" will give a right double quote. | will give a
29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
31.\" expand to `' in nroff, nothing in troff, for use with C<>.
32.tr \(*W-|\(bv\*(Tr
8b0cefbb 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 34.ie n \{\
8b0cefbb
JR
35. ds -- \(*W-
36. ds PI pi
37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
39. ds L" ""
40. ds R" ""
41. ds C` ""
42. ds C' ""
984263bc
MD
43'br\}
44.el\{\
8b0cefbb
JR
45. ds -- \|\(em\|
46. ds PI \(*p
47. ds L" ``
48. ds R" ''
984263bc 49'br\}
8b0cefbb
JR
50.\"
51.\" If the F register is turned on, we'll generate index entries on stderr for
52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
53.\" entries marked with X<> in POD. Of course, you'll have to process the
54.\" output yourself in some meaningful fashion.
55.if \nF \{\
56. de IX
57. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 58..
8b0cefbb
JR
59. nr % 0
60. rr F
984263bc 61.\}
8b0cefbb 62.\"
aac4ff6f
PA
63.\" For nroff, turn off justification. Always turn off hyphenation; it makes
64.\" way too many mistakes in technical documents.
65.hy 0
66.if n .na
67.\"
8b0cefbb
JR
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
984263bc 71.if n \{\
8b0cefbb
JR
72. ds #H 0
73. ds #V .8m
74. ds #F .3m
75. ds #[ \f1
76. ds #] \fP
984263bc
MD
77.\}
78.if t \{\
8b0cefbb
JR
79. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
80. ds #V .6m
81. ds #F 0
82. ds #[ \&
83. ds #] \&
984263bc 84.\}
8b0cefbb 85. \" simple accents for nroff and troff
984263bc 86.if n \{\
8b0cefbb
JR
87. ds ' \&
88. ds ` \&
89. ds ^ \&
90. ds , \&
91. ds ~ ~
92. ds /
984263bc
MD
93.\}
94.if t \{\
8b0cefbb
JR
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'
984263bc 101.\}
8b0cefbb 102. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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
8b0cefbb 112. \" corrections for vroff
984263bc
MD
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'
8b0cefbb 115. \" for low resolution devices (crt and lpr)
984263bc
MD
116.if \n(.H>23 .if \n(.V>19 \
117\{\
8b0cefbb
JR
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
984263bc
MD
127.\}
128.rm #[ #] #H #V #F C
8b0cefbb
JR
129.\" ========================================================================
130.\"
131.IX Title "RSA_get_ex_new_index 3"
aac4ff6f 132.TH RSA_get_ex_new_index 3 "2008-09-06" "0.9.8h" "OpenSSL"
984263bc 133.SH "NAME"
74dab6c2 134RSA_get_ex_new_index, RSA_set_ex_data, RSA_get_ex_data \- add application specific data to RSA structures
984263bc 135.SH "SYNOPSIS"
8b0cefbb 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/rsa.h>
aac4ff6f
PA
139.Ve
140.PP
141.Vb 4
984263bc
MD
142\& int RSA_get_ex_new_index(long argl, void *argp,
143\& CRYPTO_EX_new *new_func,
144\& CRYPTO_EX_dup *dup_func,
145\& CRYPTO_EX_free *free_func);
aac4ff6f
PA
146.Ve
147.PP
148.Vb 1
984263bc 149\& int RSA_set_ex_data(RSA *r, int idx, void *arg);
aac4ff6f
PA
150.Ve
151.PP
152.Vb 1
984263bc 153\& void *RSA_get_ex_data(RSA *r, int idx);
aac4ff6f
PA
154.Ve
155.PP
156.Vb 6
edae4a78
PA
157\& typedef int CRYPTO_EX_new(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
158\& int idx, long argl, void *argp);
159\& typedef void CRYPTO_EX_free(void *parent, void *ptr, CRYPTO_EX_DATA *ad,
160\& int idx, long argl, void *argp);
161\& typedef int CRYPTO_EX_dup(CRYPTO_EX_DATA *to, CRYPTO_EX_DATA *from, void *from_d,
162\& int idx, long argl, void *argp);
984263bc
MD
163.Ve
164.SH "DESCRIPTION"
8b0cefbb 165.IX Header "DESCRIPTION"
984263bc
MD
166Several OpenSSL structures can have application specific data attached to them.
167This has several potential uses, it can be used to cache data associated with
168a structure (for example the hash of some part of the structure) or some
169additional data (for example a handle to the data in an external library).
170.PP
171Since the application data can be anything at all it is passed and retrieved
172as a \fBvoid *\fR type.
173.PP
8b0cefbb 174The \fB\f(BIRSA_get_ex_new_index()\fB\fR function is initially called to \*(L"register\*(R" some
984263bc 175new application specific data. It takes three optional function pointers which
8b0cefbb 176are called when the parent structure (in this case an \s-1RSA\s0 structure) is
984263bc 177initially created, when it is copied and when it is freed up. If any or all of
8b0cefbb 178these function pointer arguments are not used they should be set to \s-1NULL\s0. The
984263bc 179precise manner in which these function pointers are called is described in more
8b0cefbb 180detail below. \fB\f(BIRSA_get_ex_new_index()\fB\fR also takes additional long and pointer
984263bc
MD
181parameters which will be passed to the supplied functions but which otherwise
182have no special meaning. It returns an \fBindex\fR which should be stored
183(typically in a static variable) and passed used in the \fBidx\fR parameter in
8b0cefbb 184the remaining functions. Each successful call to \fB\f(BIRSA_get_ex_new_index()\fB\fR
984263bc
MD
185will return an index greater than any previously returned, this is important
186because the optional functions are called in order of increasing index value.
187.PP
8b0cefbb 188\&\fB\f(BIRSA_set_ex_data()\fB\fR is used to set application specific data, the data is
984263bc
MD
189supplied in the \fBarg\fR parameter and its precise meaning is up to the
190application.
191.PP
8b0cefbb 192\&\fB\f(BIRSA_get_ex_data()\fB\fR is used to retrieve application specific data. The data
984263bc 193is returned to the application, this will be the same value as supplied to
8b0cefbb 194a previous \fB\f(BIRSA_set_ex_data()\fB\fR call.
984263bc 195.PP
8b0cefbb
JR
196\&\fB\f(BInew_func()\fB\fR is called when a structure is initially allocated (for example
197with \fB\f(BIRSA_new()\fB\fR. The parent structure members will not have any meaningful
984263bc
MD
198values at this point. This function will typically be used to allocate any
199application specific structure.
200.PP
8b0cefbb 201\&\fB\f(BIfree_func()\fB\fR is called when a structure is being freed up. The dynamic parent
984263bc
MD
202structure members should not be accessed because they will be freed up when
203this function is called.
204.PP
8b0cefbb
JR
205\&\fB\f(BInew_func()\fB\fR and \fB\f(BIfree_func()\fB\fR take the same parameters. \fBparent\fR is a
206pointer to the parent \s-1RSA\s0 structure. \fBptr\fR is a the application specific data
207(this wont be of much use in \fB\f(BInew_func()\fB\fR. \fBad\fR is a pointer to the
208\&\fB\s-1CRYPTO_EX_DATA\s0\fR structure from the parent \s-1RSA\s0 structure: the functions
209\&\fB\f(BICRYPTO_get_ex_data()\fB\fR and \fB\f(BICRYPTO_set_ex_data()\fB\fR can be called to manipulate
984263bc 210it. The \fBidx\fR parameter is the index: this will be the same value returned by
8b0cefbb 211\&\fB\f(BIRSA_get_ex_new_index()\fB\fR when the functions were initially registered. Finally
984263bc 212the \fBargl\fR and \fBargp\fR parameters are the values originally passed to the same
8b0cefbb 213corresponding parameters when \fB\f(BIRSA_get_ex_new_index()\fB\fR was called.
984263bc 214.PP
8b0cefbb
JR
215\&\fB\f(BIdup_func()\fB\fR is called when a structure is being copied. Pointers to the
216destination and source \fB\s-1CRYPTO_EX_DATA\s0\fR structures are passed in the \fBto\fR and
217\&\fBfrom\fR parameters respectively. The \fBfrom_d\fR parameter is passed a pointer to
984263bc
MD
218the source application data when the function is called, when the function returns
219the value is copied to the destination: the application can thus modify the data
220pointed to by \fBfrom_d\fR and have different values in the source and destination.
8b0cefbb
JR
221The \fBidx\fR, \fBargl\fR and \fBargp\fR parameters are the same as those in \fB\f(BInew_func()\fB\fR
222and \fB\f(BIfree_func()\fB\fR.
984263bc 223.SH "RETURN VALUES"
8b0cefbb
JR
224.IX Header "RETURN VALUES"
225\&\fB\f(BIRSA_get_ex_new_index()\fB\fR returns a new index or \-1 on failure (note 0 is a valid
984263bc
MD
226index value).
227.PP
8b0cefbb 228\&\fB\f(BIRSA_set_ex_data()\fB\fR returns 1 on success or 0 on failure.
984263bc 229.PP
8b0cefbb 230\&\fB\f(BIRSA_get_ex_data()\fB\fR returns the application data or 0 on failure. 0 may also
984263bc
MD
231be valid application data but currently it can only fail if given an invalid \fBidx\fR
232parameter.
233.PP
8b0cefbb 234\&\fB\f(BInew_func()\fB\fR and \fB\f(BIdup_func()\fB\fR should return 0 for failure and 1 for success.
984263bc 235.PP
8b0cefbb 236On failure an error code can be obtained from \fIERR_get_error\fR\|(3).
984263bc 237.SH "BUGS"
8b0cefbb
JR
238.IX Header "BUGS"
239\&\fB\f(BIdup_func()\fB\fR is currently never called.
984263bc 240.PP
8b0cefbb 241The return value of \fB\f(BInew_func()\fB\fR is ignored.
984263bc 242.PP
8b0cefbb
JR
243The \fB\f(BInew_func()\fB\fR function isn't very useful because no meaningful values are
244present in the parent \s-1RSA\s0 structure when it is called.
984263bc 245.SH "SEE ALSO"
74dab6c2 246.IX Header "SEE ALSO"
8b0cefbb
JR
247\&\fIrsa\fR\|(3), \fICRYPTO_set_ex_data\fR\|(3)
248.SH "HISTORY"
74dab6c2 249.IX Header "HISTORY"
8b0cefbb
JR
250\&\fIRSA_get_ex_new_index()\fR, \fIRSA_set_ex_data()\fR and \fIRSA_get_ex_data()\fR are
251available since SSLeay 0.9.0.