Clarify what character encoding is used in the returned UI strings

[openssl.git] / doc / man3 / UI_new.pod

diff --git a/doc/man3/UI_new.pod b/doc/man3/UI_new.pod
index 9abb697807e65e7be358adcba12aa12b2c09d366..5b98cf8d0d20adce6cf72973f5ce0d838e61f859 100644 (file)
--- a/doc/man3/UI_new.pod
+++ b/doc/man3/UI_new.pod
@@ -2,21 +2,20 @@
 
 =head1 NAME
 
-UI, UI_METHOD,
+UI,
 UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,
 UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,
 UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,
 UI_add_error_string, UI_dup_error_string, UI_construct_prompt,
 UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process,
 UI_ctrl, UI_set_default_method, UI_get_default_method, UI_get_method,
-UI_set_method, UI_OpenSSL, - user interface
+UI_set_method, UI_OpenSSL, UI_null - user interface
 
 =head1 SYNOPSIS
 
  #include <openssl/ui.h>
 
  typedef struct ui_st UI;
- typedef struct ui_method_st UI_METHOD;
 
  UI *UI_new(void);
  UI *UI_new_method(const UI_METHOD *method);
@@ -59,12 +58,13 @@ UI_set_method, UI_OpenSSL, - user interface
  const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);
 
  UI_METHOD *UI_OpenSSL(void);
+ const UI_METHOD *UI_null(void);
 
 =head1 DESCRIPTION
 
 UI stands for User Interface, and is general purpose set of routines to
 prompt the user for text-based information.  Through user-written methods
-(see L<ui_create(3)>), prompting can be done in any way
+(see L<UI_create_method(3)>), prompting can be done in any way
 imaginable, be it plain text prompting, through dialog boxes or from a
 cell phone.
 
@@ -94,10 +94,13 @@ this UI, it should be freed using UI_free().
 UI_new_method() creates a new UI using the given UI method.  When done with
 this UI, it should be freed using UI_free().
 
-UI_OpenSSL() returns the built-in UI method (note: not the default one,
-since the default can be changed.  See further on).  This method is the
-most machine/OS dependent part of OpenSSL and normally generates the
-most problems when porting.
+UI_OpenSSL() returns the built-in UI method (note: not necessarely the
+default one, since the default can be changed.  See further on).  This
+method is the most machine/OS dependent part of OpenSSL and normally
+generates the most problems when porting.
+
+UI_null() returns a UI method that does nothing.  Its use is to avoid
+getting internal defaults for passed UI_METHOD pointers.
 
 UI_free() removes a UI from memory, along with all other pieces of memory
 that's connected to it, like duplicated input strings, results and others.
@@ -158,7 +161,8 @@ UI_get0_result() returns a pointer to the result buffer associated with
 the information indexed by I<i>.
 
 UI_process() goes through the information given so far, does all the printing
-and prompting and returns.
+and prompting and returns the final status, which is -2 on out-of-band events
+(Interrupt, Cancel, ...), -1 on error and 0 on success.
 
 UI_ctrl() adds extra control for the application author.  For now, it
 understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process()
@@ -167,6 +171,8 @@ B<UI_CTRL_IS_REDOABLE>, which returns a flag saying if the used UI can
 be used again or not.
 
 UI_set_default_method() changes the default UI method to the one given.
+This function is not thread-safe and should not be called at the same time
+as other OpenSSL functions.
 
 UI_get_default_method() returns a pointer to the current default UI method.
 
@@ -174,9 +180,20 @@ UI_get_method() returns the UI method associated with a given UI.
 
 UI_set_method() changes the UI method associated with a given UI.
 
+=head1 NOTES
+
+The resulting strings that the built in method UI_OpenSSL() generate
+are assumed to be encoded according to the current locale or (for
+Windows) code page.
+For applications having different demands, these strings need to be
+converted appropriately by the caller.
+For Windows, if the OPENSSL_WIN32_UTF8 environment variable is set,
+the built-in method UI_OpenSSL() will produce UTF-8 encoded strings
+instead.
+
 =head1 COPYRIGHT
 
-Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2001-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy