Debian Codegraph @

upstream/debian-unstable/man3/UI_create_method.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "UI_CREATE_METHOD 3SSL"
58 .TH UI_CREATE_METHOD 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 UI_METHOD,
65 UI_create_method, UI_destroy_method, UI_method_set_opener,
66 UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader,
67 UI_method_set_closer, UI_method_set_data_duplicator,
68 UI_method_set_prompt_constructor, UI_method_set_ex_data,
69 UI_method_get_opener, UI_method_get_writer, UI_method_get_flusher,
70 UI_method_get_reader, UI_method_get_closer,
71 UI_method_get_data_duplicator, UI_method_get_data_destructor,
72 UI_method_get_prompt_constructor, UI_method_get_ex_data \- user
73 interface method creation and destruction
74 .SH SYNOPSIS
75 .IX Header "SYNOPSIS"
76 .Vb 1
77 \& #include <openssl/ui.h>
78 \&
79 \& typedef struct ui_method_st UI_METHOD;
80 \&
81 \& UI_METHOD *UI_create_method(const char *name);
82 \& void UI_destroy_method(UI_METHOD *ui_method);
83 \& int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));
84 \& int UI_method_set_writer(UI_METHOD *method,
85 \& int (*writer) (UI *ui, UI_STRING *uis));
86 \& int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));
87 \& int UI_method_set_reader(UI_METHOD *method,
88 \& int (*reader) (UI *ui, UI_STRING *uis));
89 \& int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));
90 \& int UI_method_set_data_duplicator(UI_METHOD *method,
91 \& void *(*duplicator) (UI *ui, void *ui_data),
92 \& void (*destructor)(UI *ui, void *ui_data));
93 \& int UI_method_set_prompt_constructor(UI_METHOD *method,
94 \& char *(*prompt_constructor) (UI *ui,
95 \& const char
96 \& *object_desc,
97 \& const char
98 \& *object_name));
99 \& int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);
100 \& int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);
101 \& int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);
102 \& int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);
103 \& int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);
104 \& int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);
105 \& char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))
106 \& (UI *, const char *, const char *);
107 \& void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *);
108 \& void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *);
109 \& const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);
110 .Ve
111 .SH DESCRIPTION
112 .IX Header "DESCRIPTION"
113 A method contains a few functions that implement the low-level of the
114 User Interface.
115 These functions are:
116 .IP "an opener" 4
117 .IX Item "an opener"
118 This function takes a reference to a UI and starts a session, for
119 example by opening a channel to a tty, or by creating a dialog box.
120 .IP "a writer" 4
121 .IX Item "a writer"
122 This function takes a reference to a UI and a UI String, and writes
123 the string where appropriate, maybe to the tty, maybe added as a field
124 label in a dialog box.
125 Note that this gets fed all strings associated with a UI, one after
126 the other, so care must be taken which ones it actually uses.
127 .IP "a flusher" 4
128 .IX Item "a flusher"
129 This function takes a reference to a UI, and flushes everything that
130 has been output so far.
131 For example, if the method builds up a dialog box, this can be used to
132 actually display it and accepting input ended with a pressed button.
133 .IP "a reader" 4
134 .IX Item "a reader"
135 This function takes a reference to a UI and a UI string and reads off
136 the given prompt, maybe from the tty, maybe from a field in a dialog
137 box.
138 Note that this gets fed all strings associated with a UI, one after
139 the other, so care must be taken which ones it actually uses.
140 .IP "a closer" 4
141 .IX Item "a closer"
142 This function takes a reference to a UI, and closes the session, maybe
143 by closing the channel to the tty, maybe by destroying a dialog box.
144 .PP
145 All of these functions are expected to return 0 on error, 1 on
146 success, or \-1 on out-off-band events, for example if some prompting
147 has been cancelled (by pressing Ctrl-C, for example).
148 Only the flusher or the reader are expected to return \-1.
149 If returned by another of the functions, it's treated as if 0 was
150 returned.
151 .PP
152 Regarding the writer and the reader, don't assume the former should
153 only write and don't assume the latter should only read.
154 This depends on the needs of the method.
155 .PP
156 For example, a typical tty reader wouldn't write the prompts in the
157 write, but would rather do so in the reader, because of the sequential
158 nature of prompting on a tty.
159 This is how the \fBUI_OpenSSL()\fR method does it.
160 .PP
161 In contrast, a method that builds up a dialog box would add all prompt
162 text in the writer, have all input read in the flusher and store the
163 results in some temporary buffer, and finally have the reader just
164 fetch those results.
165 .PP
166 The central function that uses these method functions is \fBUI_process()\fR,
167 and it does it in five steps:
168 .IP 1. 4
169 Open the session using the opener function if that one's defined.
170 If an error occurs, jump to 5.
171 .IP 2. 4
172 For every UI String associated with the UI, call the writer function
173 if that one's defined.
174 If an error occurs, jump to 5.
175 .IP 3. 4
176 Flush everything using the flusher function if that one's defined.
177 If an error occurs, jump to 5.
178 .IP 4. 4
179 For every UI String associated with the UI, call the reader function
180 if that one's defined.
181 If an error occurs, jump to 5.
182 .IP 5. 4
183 Close the session using the closer function if that one's defined.
184 .PP
185 \&\fBUI_create_method()\fR creates a new UI method with a given \fBname\fR.
186 .PP
187 \&\fBUI_destroy_method()\fR destroys the given UI method \fBui_method\fR.
188 .PP
189 \&\fBUI_method_set_opener()\fR, \fBUI_method_set_writer()\fR,
190 \&\fBUI_method_set_flusher()\fR, \fBUI_method_set_reader()\fR and
191 \&\fBUI_method_set_closer()\fR set the five main method function to the given
192 function pointer.
193 .PP
194 \&\fBUI_method_set_data_duplicator()\fR sets the user data duplicator and destructor.
195 See \fBUI_dup_user_data\fR\|(3).
196 .PP
197 \&\fBUI_method_set_prompt_constructor()\fR sets the prompt constructor.
198 See \fBUI_construct_prompt\fR\|(3).
199 .PP
200 \&\fBUI_method_set_ex_data()\fR sets application specific data with a given
201 EX_DATA index.
202 See \fBCRYPTO_get_ex_new_index\fR\|(3) for general information on how to
203 get that index.
204 .PP
205 \&\fBUI_method_get_opener()\fR, \fBUI_method_get_writer()\fR,
206 \&\fBUI_method_get_flusher()\fR, \fBUI_method_get_reader()\fR,
207 \&\fBUI_method_get_closer()\fR, \fBUI_method_get_data_duplicator()\fR,
208 \&\fBUI_method_get_data_destructor()\fR and \fBUI_method_get_prompt_constructor()\fR
209 return the different method functions.
210 .PP
211 \&\fBUI_method_get_ex_data()\fR returns the application data previously stored
212 with \fBUI_method_set_ex_data()\fR.
213 .SH "RETURN VALUES"
214 .IX Header "RETURN VALUES"
215 \&\fBUI_create_method()\fR returns a UI_METHOD pointer on success, NULL on
216 error.
217 .PP
218 \&\fBUI_method_set_opener()\fR, \fBUI_method_set_writer()\fR,
219 \&\fBUI_method_set_flusher()\fR, \fBUI_method_set_reader()\fR,
220 \&\fBUI_method_set_closer()\fR, \fBUI_method_set_data_duplicator()\fR and
221 \&\fBUI_method_set_prompt_constructor()\fR
222 return 0 on success, \-1 if the given \fBmethod\fR is NULL.
223 .PP
224 \&\fBUI_method_set_ex_data()\fR returns 1 on success and 0 on error (because
225 \&\fBCRYPTO_set_ex_data()\fR does so).
226 .PP
227 \&\fBUI_method_get_opener()\fR, \fBUI_method_get_writer()\fR,
228 \&\fBUI_method_get_flusher()\fR, \fBUI_method_get_reader()\fR,
229 \&\fBUI_method_get_closer()\fR, \fBUI_method_get_data_duplicator()\fR,
230 \&\fBUI_method_get_data_destructor()\fR and \fBUI_method_get_prompt_constructor()\fR
231 return the requested function pointer if it's set in the method,
232 otherwise NULL.
233 .PP
234 \&\fBUI_method_get_ex_data()\fR returns a pointer to the application specific
235 data associated with the method.
236 .SH "SEE ALSO"
237 .IX Header "SEE ALSO"
238 \&\fBUI\fR\|(3), \fBCRYPTO_get_ex_data\fR\|(3), \fBUI_STRING\fR\|(3)
239 .SH HISTORY
240 .IX Header "HISTORY"
241 The \fBUI_method_set_data_duplicator()\fR, \fBUI_method_get_data_duplicator()\fR
242 and \fBUI_method_get_data_destructor()\fR functions were added in OpenSSL 1.1.1.
243 .SH COPYRIGHT
244 .IX Header "COPYRIGHT"
245 Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved.
246 .PP
247 Licensed under the Apache License 2.0 (the "License"). You may not use
248 this file except in compliance with the License. You can obtain a copy
249 in the file LICENSE in the source distribution or at
250 <https://www.openssl.org/source/license.html>.