]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - secure/lib/libcrypto/man/UI_create_method.3
Regen manual pages.
[FreeBSD/FreeBSD.git] / secure / lib / libcrypto / man / UI_create_method.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 "UI_CREATE_METHOD 3"
132 .TH UI_CREATE_METHOD 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 UI_METHOD, UI_create_method, UI_destroy_method, UI_method_set_opener, UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader, UI_method_set_closer, UI_method_set_data_duplicator, UI_method_set_prompt_constructor, UI_method_set_ex_data, UI_method_get_opener, UI_method_get_writer, UI_method_get_flusher, UI_method_get_reader, UI_method_get_closer, UI_method_get_data_duplicator, UI_method_get_data_destructor, UI_method_get_prompt_constructor, UI_method_get_ex_data \- user interface method creation and destruction
139 .SH "SYNOPSIS"
140 .IX Header "SYNOPSIS"
141 .Vb 1
142 \& #include <openssl/ui.h>
143 \&
144 \& typedef struct ui_method_st UI_METHOD;
145 \&
146 \& UI_METHOD *UI_create_method(const char *name);
147 \& void UI_destroy_method(UI_METHOD *ui_method);
148 \& int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));
149 \& int UI_method_set_writer(UI_METHOD *method,
150 \&                          int (*writer) (UI *ui, UI_STRING *uis));
151 \& int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));
152 \& int UI_method_set_reader(UI_METHOD *method,
153 \&                          int (*reader) (UI *ui, UI_STRING *uis));
154 \& int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));
155 \& int UI_method_set_data_duplicator(UI_METHOD *method,
156 \&                                   void *(*duplicator) (UI *ui, void *ui_data),
157 \&                                   void (*destructor)(UI *ui, void *ui_data));
158 \& int UI_method_set_prompt_constructor(UI_METHOD *method,
159 \&                                      char *(*prompt_constructor) (UI *ui,
160 \&                                                                   const char
161 \&                                                                   *object_desc,
162 \&                                                                   const char
163 \&                                                                   *object_name));
164 \& int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);
165 \& int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);
166 \& int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);
167 \& int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);
168 \& int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);
169 \& int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);
170 \& char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))
171 \&     (UI *, const char *, const char *);
172 \& void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *);
173 \& void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *);
174 \& const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);
175 .Ve
176 .SH "DESCRIPTION"
177 .IX Header "DESCRIPTION"
178 A method contains a few functions that implement the low level of the
179 User Interface.
180 These functions are:
181 .IP "an opener" 4
182 .IX Item "an opener"
183 This function takes a reference to a \s-1UI\s0 and starts a session, for
184 example by opening a channel to a tty, or by creating a dialog box.
185 .IP "a writer" 4
186 .IX Item "a writer"
187 This function takes a reference to a \s-1UI\s0 and a \s-1UI\s0 String, and writes
188 the string where appropriate, maybe to the tty, maybe added as a field
189 label in a dialog box.
190 Note that this gets fed all strings associated with a \s-1UI,\s0 one after
191 the other, so care must be taken which ones it actually uses.
192 .IP "a flusher" 4
193 .IX Item "a flusher"
194 This function takes a reference to a \s-1UI,\s0 and flushes everything that
195 has been output so far.
196 For example, if the method builds up a dialog box, this can be used to
197 actually display it and accepting input ended with a pressed button.
198 .IP "a reader" 4
199 .IX Item "a reader"
200 This function takes a reference to a \s-1UI\s0 and a \s-1UI\s0 string and reads off
201 the given prompt, maybe from the tty, maybe from a field in a dialog
202 box.
203 Note that this gets fed all strings associated with a \s-1UI,\s0 one after
204 the other, so care must be taken which ones it actually uses.
205 .IP "a closer" 4
206 .IX Item "a closer"
207 This function takes a reference to a \s-1UI,\s0 and closes the session, maybe
208 by closing the channel to the tty, maybe by destroying a dialog box.
209 .PP
210 All of these functions are expected to return 0 on error, 1 on
211 success, or \-1 on out-off-band events, for example if some prompting
212 has been cancelled (by pressing Ctrl-C, for example).
213 Only the flusher or the reader are expected to return \-1.
214 If returned by another of the functions, it's treated as if 0 was
215 returned.
216 .PP
217 Regarding the writer and the reader, don't assume the former should
218 only write and don't assume the latter should only read.
219 This depends on the needs of the method.
220 .PP
221 For example, a typical tty reader wouldn't write the prompts in the
222 write, but would rather do so in the reader, because of the sequential
223 nature of prompting on a tty.
224 This is how the \fIUI_OpenSSL()\fR method does it.
225 .PP
226 In contrast, a method that builds up a dialog box would add all prompt
227 text in the writer, have all input read in the flusher and store the
228 results in some temporary buffer, and finally have the reader just
229 fetch those results.
230 .PP
231 The central function that uses these method functions is \fIUI_process()\fR,
232 and it does it in five steps:
233 .IP "1." 4
234 Open the session using the opener function if that one's defined.
235 If an error occurs, jump to 5.
236 .IP "2." 4
237 For every \s-1UI\s0 String associated with the \s-1UI,\s0 call the writer function
238 if that one's defined.
239 If an error occurs, jump to 5.
240 .IP "3." 4
241 Flush everything using the flusher function if that one's defined.
242 If an error occurs, jump to 5.
243 .IP "4." 4
244 For every \s-1UI\s0 String associated with the \s-1UI,\s0 call the reader function
245 if that one's defined.
246 If an error occurs, jump to 5.
247 .IP "5." 4
248 Close the session using the closer function if that one's defined.
249 .PP
250 \&\fIUI_create_method()\fR creates a new \s-1UI\s0 method with a given \fBname\fR.
251 .PP
252 \&\fIUI_destroy_method()\fR destroys the given \s-1UI\s0 method \fBui_method\fR.
253 .PP
254 \&\fIUI_method_set_opener()\fR, \fIUI_method_set_writer()\fR,
255 \&\fIUI_method_set_flusher()\fR, \fIUI_method_set_reader()\fR and
256 \&\fIUI_method_set_closer()\fR set the five main method function to the given
257 function pointer.
258 .PP
259 \&\fIUI_method_set_data_duplicator()\fR sets the user data duplicator and destructor.
260 See \fIUI_dup_user_data\fR\|(3).
261 .PP
262 \&\fIUI_method_set_prompt_constructor()\fR sets the prompt constructor.
263 See \fIUI_construct_prompt\fR\|(3).
264 .PP
265 \&\fIUI_method_set_ex_data()\fR sets application specific data with a given
266 \&\s-1EX_DATA\s0 index.
267 See \fICRYPTO_get_ex_new_index\fR\|(3) for general information on how to
268 get that index.
269 .PP
270 \&\fIUI_method_get_opener()\fR, \fIUI_method_get_writer()\fR,
271 \&\fIUI_method_get_flusher()\fR, \fIUI_method_get_reader()\fR,
272 \&\fIUI_method_get_closer()\fR, \fIUI_method_get_data_duplicator()\fR,
273 \&\fIUI_method_get_data_destructor()\fR and \fIUI_method_get_prompt_constructor()\fR
274 return the different method functions.
275 .PP
276 \&\fIUI_method_get_ex_data()\fR returns the application data previously stored
277 with \fIUI_method_set_ex_data()\fR.
278 .SH "RETURN VALUES"
279 .IX Header "RETURN VALUES"
280 \&\fIUI_create_method()\fR returns a \s-1UI_METHOD\s0 pointer on success, \s-1NULL\s0 on
281 error.
282 .PP
283 \&\fIUI_method_set_opener()\fR, \fIUI_method_set_writer()\fR,
284 \&\fIUI_method_set_flusher()\fR, \fIUI_method_set_reader()\fR,
285 \&\fIUI_method_set_closer()\fR, \fIUI_method_set_data_duplicator()\fR and
286 \&\fIUI_method_set_prompt_constructor()\fR
287 return 0 on success, \-1 if the given \fBmethod\fR is \s-1NULL.\s0
288 .PP
289 \&\fIUI_method_set_ex_data()\fR returns 1 on success and 0 on error (because
290 \&\fICRYPTO_set_ex_data()\fR does so).
291 .PP
292 \&\fIUI_method_get_opener()\fR, \fIUI_method_get_writer()\fR,
293 \&\fIUI_method_get_flusher()\fR, \fIUI_method_get_reader()\fR,
294 \&\fIUI_method_get_closer()\fR, \fIUI_method_get_data_duplicator()\fR,
295 \&\fIUI_method_get_data_destructor()\fR and \fIUI_method_get_prompt_constructor()\fR
296 return the requested function pointer if it's set in the method,
297 otherwise \s-1NULL.\s0
298 .PP
299 \&\fIUI_method_get_ex_data()\fR returns a pointer to the application specific
300 data associated with the method.
301 .SH "SEE ALSO"
302 .IX Header "SEE ALSO"
303 \&\s-1\fIUI\s0\fR\|(3), \fICRYPTO_get_ex_data\fR\|(3), \s-1\fIUI_STRING\s0\fR\|(3)
304 .SH "HISTORY"
305 .IX Header "HISTORY"
306 \&\fIUI_method_set_data_duplicator()\fR, \fIUI_method_get_data_duplicator()\fR and
307 \&\fIUI_method_get_data_destructor()\fR
308 were added in OpenSSL 1.1.1.
309 .SH "COPYRIGHT"
310 .IX Header "COPYRIGHT"
311 Copyright 2001\-2016 The OpenSSL Project Authors. All Rights Reserved.
312 .PP
313 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
314 this file except in compliance with the License.  You can obtain a copy
315 in the file \s-1LICENSE\s0 in the source distribution or at
316 <https://www.openssl.org/source/license.html>.