RT3488: Update doc for OPENSSL_config

Fix CONF_load_modules to CONF_modules_load.
Document that it calls exit.
Advise against using it now.
Add an error print to stderr.
Reviewed-by: NMatt Caswell <matt@openssl.org>

crypto/conf/conf_sap.c

@@ -99,6 +99,7 @@ void OPENSSL_config(const char *config_name)
 			ERR_print_errors(bio_err);
 			BIO_free(bio_err);
 			}
+		fprintf(stderr, "OpenSSL could not auto-configure.\n");
 		exit(1);
 		}
 

doc/crypto/OPENSSL_config.pod

@@ -15,31 +15,33 @@ OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions
 
 OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf>
 configuration file name using B<config_name>. If B<config_name> is NULL then
-the default name B<openssl_conf> will be used. Any errors are ignored. Further
-calls to OPENSSL_config() will have no effect. The configuration file format
-is documented in the L<conf(5)|conf(5)> manual page.
+the file specified in the environment variable B<OPENSSL_CONF> will be used,
+and if that is not set then a system default location is used.
+In case of error, a message is printed to B<stderr> and the routine
+exit's.
+Multiple calls have no effect.
 
 OPENSSL_no_config() disables configuration. If called before OPENSSL_config()
 no configuration takes place.
 
-=head1 NOTES
+Applications should free up configuration at application closedown by calling
+CONF_modules_free().
 
-It is B<strongly> recommended that B<all> new applications call OPENSSL_config()
-or the more sophisticated functions such as CONF_modules_load() during
-initialization (that is before starting any threads). By doing this
-an application does not need to keep track of all configuration options
-and some new functionality can be supported automatically.
+If the application is built with B<OPENSSL_LOAD_CONF> defined, then a
+call to OpenSSL_add_all_algorithms() will implicitly call OPENSSL_config()
+first.
 
-It is also possible to automatically call OPENSSL_config() when an application
-calls OPENSSL_add_all_algorithms() by compiling an application with the
-preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. In this way configuration
-can be added without source changes.
+=head1 NOTES
 
-The environment variable B<OPENSSL_CONF> can be set to specify the location
-of the configuration file.
- 
-Currently ASN1 OBJECTs and ENGINE configuration can be performed future
-versions of OpenSSL will add new configuration options.
+The OPENSSL_config() function is designed to be a very simple "call it and
+forget it" function.
+It is however B<much> better than nothing. Applications which need finer
+control over their configuration functionality should use the configuration
+functions such as CONF_modules_load() directly.
+
+It is B<strongly> recommended that B<all> new applications call
+CONF_modules_load() during
+initialization (that is before starting any threads).
 
 There are several reasons why calling the OpenSSL configuration routines is
 advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7.
@@ -52,27 +54,14 @@ application calls OPENSSL_config() it doesn't need to know or care about
 ENGINE control operations because they can be performed by editing a
 configuration file.
 
-Applications should free up configuration at application closedown by calling
-CONF_modules_free().
-
-=head1 RESTRICTIONS
-
-The OPENSSL_config() function is designed to be a very simple "call it and
-forget it" function. As a result its behaviour is somewhat limited. It ignores
-all errors silently and it can only load from the standard configuration file
-location for example.
-
-It is however B<much> better than nothing. Applications which need finer
-control over their configuration functionality should use the configuration
-functions such as CONF_load_modules() directly.
-
 =head1 RETURN VALUES
 
 Neither OPENSSL_config() nor OPENSSL_no_config() return a value.
 
 =head1 SEE ALSO
 
-L<conf(5)|conf(5)>, L<CONF_load_modules_file(3)|CONF_load_modules_file(3)>,
+L<conf(5)|conf(5)>,
+L<CONF_modules_load_file(3)|CONF_modules_load_file(3)>,
 L<CONF_modules_free(3)|CONF_modules_free(3)>
 
 =head1 HISTORY