Add UI functions to set result with explicit length and to retrieve the length
[openssl.git] / doc / man3 / UI_STRING.pod
index 340d9b2..5a464a3 100644 (file)
@@ -4,9 +4,9 @@
 
 UI_STRING, UI_string_types, UI_get_string_type,
 UI_get_input_flags, UI_get0_output_string,
-UI_get0_action_string, UI_get0_result_string,
+UI_get0_action_string, UI_get0_result_string, UI_get_result_string_length,
 UI_get0_test_string, UI_get_result_minsize,
-UI_get_result_maxsize, UI_set_result
+UI_get_result_maxsize, UI_set_result, UI_set_result_ex
 - User interface string parsing
 
 =head1 SYNOPSIS
@@ -29,10 +29,12 @@ UI_get_result_maxsize, UI_set_result
  const char *UI_get0_output_string(UI_STRING *uis);
  const char *UI_get0_action_string(UI_STRING *uis);
  const char *UI_get0_result_string(UI_STRING *uis);
+ int UI_get_result_string_length(UI_STRING *uis);
  const char *UI_get0_test_string(UI_STRING *uis);
  int UI_get_result_minsize(UI_STRING *uis);
  int UI_get_result_maxsize(UI_STRING *uis);
  int UI_set_result(UI *ui, UI_STRING *uis, const char *result);
+ int UI_set_result_ex(UI *ui, UI_STRING *uis, const char *result, int len);
 
 =head1 DESCRIPTION
 
@@ -60,9 +62,11 @@ associated with a B<UIT_BOOLEAN> type B<UI_STRING>.
 For all other B<UI_STRING> types, NULL is returned.
 See L<UI_add_input_boolean(3)>.
 
-UI_get0_result_string() is used to retrieve the result of a prompt.
+UI_get0_result_string() and UI_get_result_string_length() are used to
+retrieve the result of a prompt and its length.
 This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings.
-For all other B<UI_STRING> types, NULL is returned.
+For all other B<UI_STRING> types, UI_get0_result_string() returns NULL
+and UI_get_result_string_length() returns -1.
 
 UI_get0_test_string() is used to retrieve the string to compare the
 prompt result with.
@@ -74,7 +78,7 @@ retrieve the minimum and maximum required size of the result.
 This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings.
 For all other B<UI_STRING> types, -1 is returned.
 
-UI_set_result() is used to set the result value of a prompt.
+UI_set_result_ex() is used to set the result value of a prompt and its length.
 For B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, this sets the
 result retrievable with UI_get0_result_string() by copying the
 contents of B<result> if its length fits the minimum and maximum size
@@ -88,6 +92,11 @@ set to the NUL char C<\0>.
 See L<UI_add_input_boolean(3)> for more information on B<ok_chars> and
 B<cancel_chars>.
 
+UI_set_result() does the same thing as UI_set_result_ex(), but calculates
+its length internally.
+It expects the string to be terminated with a NUL byte, and is therefore
+only useful with normal C strings.
+
 =head1 RETURN VALUES
 
 UI_get_string_type() returns the UI string type.
@@ -103,6 +112,10 @@ UI_get0_result_string() returns the UI string result buffer for
 B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, NULL for any other
 type.
 
+UI_get_result_string_length() returns the UI string result buffer's
+content length for B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings,
+-1 for any other type.
+
 UI_get0_test_string() returns the UI string action description
 string for B<UIT_VERIFY> type UI strings, NULL for any other type.