Debian Codegraph @

upstream/debian-unstable/man3/UI_STRING.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_STRING 3SSL"
58 .TH UI_STRING 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_STRING, UI_string_types, UI_get_string_type,
65 UI_get_input_flags, UI_get0_output_string,
66 UI_get0_action_string, UI_get0_result_string, UI_get_result_string_length,
67 UI_get0_test_string, UI_get_result_minsize,
68 UI_get_result_maxsize, UI_set_result, UI_set_result_ex
69 \&\- User interface string parsing
70 .SH SYNOPSIS
71 .IX Header "SYNOPSIS"
72 .Vb 1
73 \& #include <openssl/ui.h>
74 \&
75 \& typedef struct ui_string_st UI_STRING;
76 \&
77 \& enum UI_string_types {
78 \& UIT_NONE = 0,
79 \& UIT_PROMPT, /* Prompt for a string */
80 \& UIT_VERIFY, /* Prompt for a string and verify */
81 \& UIT_BOOLEAN, /* Prompt for a yes/no response */
82 \& UIT_INFO, /* Send info to the user */
83 \& UIT_ERROR /* Send an error message to the user */
84 \& };
85 \&
86 \& enum UI_string_types UI_get_string_type(UI_STRING *uis);
87 \& int UI_get_input_flags(UI_STRING *uis);
88 \& const char *UI_get0_output_string(UI_STRING *uis);
89 \& const char *UI_get0_action_string(UI_STRING *uis);
90 \& const char *UI_get0_result_string(UI_STRING *uis);
91 \& int UI_get_result_string_length(UI_STRING *uis);
92 \& const char *UI_get0_test_string(UI_STRING *uis);
93 \& int UI_get_result_minsize(UI_STRING *uis);
94 \& int UI_get_result_maxsize(UI_STRING *uis);
95 \& int UI_set_result(UI *ui, UI_STRING *uis, const char *result);
96 \& int UI_set_result_ex(UI *ui, UI_STRING *uis, const char *result, int len);
97 .Ve
98 .SH DESCRIPTION
99 .IX Header "DESCRIPTION"
100 The \fBUI_STRING\fR gets created internally and added to a \fBUI\fR whenever
101 one of the functions \fBUI_add_input_string()\fR, \fBUI_dup_input_string()\fR,
102 \&\fBUI_add_verify_string()\fR, \fBUI_dup_verify_string()\fR,
103 \&\fBUI_add_input_boolean()\fR, \fBUI_dup_input_boolean()\fR, \fBUI_add_info_string()\fR,
104 \&\fBUI_dup_info_string()\fR, \fBUI_add_error_string()\fR or \fBUI_dup_error_string()\fR
105 is called.
106 For a \fBUI_METHOD\fR user, there's no need to know more.
107 For a \fBUI_METHOD\fR creator, it is of interest to fetch text from these
108 \&\fBUI_STRING\fR objects as well as adding results to some of them.
109 .PP
110 \&\fBUI_get_string_type()\fR is used to retrieve the type of the given
111 \&\fBUI_STRING\fR.
112 .PP
113 \&\fBUI_get_input_flags()\fR is used to retrieve the flags associated with the
114 given \fBUI_STRING\fR.
115 .PP
116 \&\fBUI_get0_output_string()\fR is used to retrieve the actual string to
117 output (prompt, info, error, ...).
118 .PP
119 \&\fBUI_get0_action_string()\fR is used to retrieve the action description
120 associated with a \fBUIT_BOOLEAN\fR type \fBUI_STRING\fR.
121 For all other \fBUI_STRING\fR types, NULL is returned.
122 See \fBUI_add_input_boolean\fR\|(3).
123 .PP
124 \&\fBUI_get0_result_string()\fR and \fBUI_get_result_string_length()\fR are used to
125 retrieve the result of a prompt and its length.
126 This is only useful for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type strings.
127 For all other \fBUI_STRING\fR types, \fBUI_get0_result_string()\fR returns NULL
128 and \fBUI_get_result_string_length()\fR returns \-1.
129 .PP
130 \&\fBUI_get0_test_string()\fR is used to retrieve the string to compare the
131 prompt result with.
132 This is only useful for \fBUIT_VERIFY\fR type strings.
133 For all other \fBUI_STRING\fR types, NULL is returned.
134 .PP
135 \&\fBUI_get_result_minsize()\fR and \fBUI_get_result_maxsize()\fR are used to
136 retrieve the minimum and maximum required size of the result.
137 This is only useful for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type strings.
138 For all other \fBUI_STRING\fR types, \-1 is returned.
139 .PP
140 \&\fBUI_set_result_ex()\fR is used to set the result value of a prompt and its length.
141 For \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type UI strings, this sets the
142 result retrievable with \fBUI_get0_result_string()\fR by copying the
143 contents of \fBresult\fR if its length fits the minimum and maximum size
144 requirements.
145 For \fBUIT_BOOLEAN\fR type UI strings, this sets the first character of
146 the result retrievable with \fBUI_get0_result_string()\fR to the first
147 \&\fBok_char\fR given with \fBUI_add_input_boolean()\fR or \fBUI_dup_input_boolean()\fR
148 if the \fBresult\fR matched any of them, or the first of the
149 \&\fBcancel_chars\fR if the \fBresult\fR matched any of them, otherwise it's
150 set to the NUL char \f(CW\*(C`\e0\*(C'\fR.
151 See \fBUI_add_input_boolean\fR\|(3) for more information on \fBok_chars\fR and
152 \&\fBcancel_chars\fR.
153 .PP
154 \&\fBUI_set_result()\fR does the same thing as \fBUI_set_result_ex()\fR, but calculates
155 its length internally.
156 It expects the string to be terminated with a NUL byte, and is therefore
157 only useful with normal C strings.
158 .SH "RETURN VALUES"
159 .IX Header "RETURN VALUES"
160 \&\fBUI_get_string_type()\fR returns the UI string type.
161 .PP
162 \&\fBUI_get_input_flags()\fR returns the UI string flags.
163 .PP
164 \&\fBUI_get0_output_string()\fR returns the UI string output string.
165 .PP
166 \&\fBUI_get0_action_string()\fR returns the UI string action description
167 string for \fBUIT_BOOLEAN\fR type UI strings, NULL for any other type.
168 .PP
169 \&\fBUI_get0_result_string()\fR returns the UI string result buffer for
170 \&\fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type UI strings, NULL for any other
171 type.
172 .PP
173 \&\fBUI_get_result_string_length()\fR returns the UI string result buffer's
174 content length for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type UI strings,
175 \&\-1 for any other type.
176 .PP
177 \&\fBUI_get0_test_string()\fR returns the UI string action description
178 string for \fBUIT_VERIFY\fR type UI strings, NULL for any other type.
179 .PP
180 \&\fBUI_get_result_minsize()\fR returns the minimum allowed result size for
181 the UI string for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type strings,
182 \&\-1 for any other type.
183 .PP
184 \&\fBUI_get_result_maxsize()\fR returns the minimum allowed result size for
185 the UI string for \fBUIT_PROMPT\fR and \fBUIT_VERIFY\fR type strings,
186 \&\-1 for any other type.
187 .PP
188 \&\fBUI_set_result()\fR returns 0 on success or when the UI string is of any
189 type other than \fBUIT_PROMPT\fR, \fBUIT_VERIFY\fR or \fBUIT_BOOLEAN\fR, \-1 on
190 error.
191 .SH "SEE ALSO"
192 .IX Header "SEE ALSO"
193 \&\fBUI\fR\|(3)
194 .SH COPYRIGHT
195 .IX Header "COPYRIGHT"
196 Copyright 2001\-2018 The OpenSSL Project Authors. All Rights Reserved.
197 .PP
198 Licensed under the Apache License 2.0 (the "License"). You may not use
199 this file except in compliance with the License. You can obtain a copy
200 in the file LICENSE in the source distribution or at
201 <https://www.openssl.org/source/license.html>.