diff options
author | marha <marha@users.sourceforge.net> | 2015-04-20 23:05:23 +0200 |
---|---|---|
committer | marha <marha@users.sourceforge.net> | 2015-04-20 23:05:23 +0200 |
commit | 0f7871ff824bcf064db3ab6bdfe26645ba6c8087 (patch) | |
tree | 90d3d2b6112e083289c9cf68146852087814f6d3 /openssl/doc/crypto/CONF_modules_load_file.pod | |
parent | 934184bfecd402aae891b8740d788b486aa7269f (diff) | |
parent | 2a00e489122f6c4b525090dbdba2855a2ea2d519 (diff) | |
download | vcxsrv-0f7871ff824bcf064db3ab6bdfe26645ba6c8087.tar.gz vcxsrv-0f7871ff824bcf064db3ab6bdfe26645ba6c8087.tar.bz2 vcxsrv-0f7871ff824bcf064db3ab6bdfe26645ba6c8087.zip |
Merge remote-tracking branch 'origin/released'
Conflicts:
openssl/Makefile
Diffstat (limited to 'openssl/doc/crypto/CONF_modules_load_file.pod')
-rw-r--r-- | openssl/doc/crypto/CONF_modules_load_file.pod | 87 |
1 files changed, 82 insertions, 5 deletions
diff --git a/openssl/doc/crypto/CONF_modules_load_file.pod b/openssl/doc/crypto/CONF_modules_load_file.pod index 0c4d92685..cc0b537b8 100644 --- a/openssl/doc/crypto/CONF_modules_load_file.pod +++ b/openssl/doc/crypto/CONF_modules_load_file.pod @@ -9,9 +9,9 @@ #include <openssl/conf.h> int CONF_modules_load_file(const char *filename, const char *appname, - unsigned long flags); + unsigned long flags); int CONF_modules_load(const CONF *cnf, const char *appname, - unsigned long flags); + unsigned long flags); =head1 DESCRIPTION @@ -22,7 +22,7 @@ NULL the standard OpenSSL application name B<openssl_conf> is used. The behaviour can be cutomized using B<flags>. CONF_modules_load() is idential to CONF_modules_load_file() except it -read configuration information from B<cnf>. +reads configuration information from B<cnf>. =head1 NOTES @@ -30,7 +30,7 @@ The following B<flags> are currently recognized: B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual configuration modules are ignored. If not set the first module error is -considered fatal and no further modules are loads. +considered fatal and no further modules are loaded. Normally any modules errors will add error information to the error queue. If B<CONF_MFLAGS_SILENT> is set no error information is added. @@ -42,7 +42,84 @@ B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file() ignore missing configuration files. Normally a missing configuration file return an error. -=head1 RETURN VALUE +B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the +default section pointed to by B<openssl_conf> if B<appname> does not exist. + +Applications should call these functions after loading builtin modules using +OPENSSL_load_builtin_modules(), any ENGINEs for example using +ENGINE_load_builtin_engines(), any algorithms for example +OPENSSL_add_all_algorithms() and (if the application uses libssl) +SSL_library_init(). + +By using CONF_modules_load_file() with appropriate flags an application can +customise application configuration to best suit its needs. In some cases the +use of a configuration file is optional and its absence is not an error: in +this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set. + +Errors during configuration may also be handled differently by different +applications. For example in some cases an error may simply print out a warning +message and the application continue. In other cases an application might +consider a configuration file error as fatal and exit immediately. + +Applications can use the CONF_modules_load() function if they wish to load a +configuration file themselves and have finer control over how errors are +treated. + +=head1 EXAMPLES + +Load a configuration file and print out any errors and exit (missing file +considered fatal): + + if (CONF_modules_load_file(NULL, NULL, 0) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + +Load default configuration file using the section indicated by "myapp", +tolerate missing files, but exit on other errors: + + if (CONF_modules_load_file(NULL, "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + +Load custom configuration file and section, only print warnings on error, +missing configuration file ignored: + + if (CONF_modules_load_file("/something/app.cnf", "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "WARNING: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + } + +Load and parse configuration file manually, custom error handling: + + FILE *fp; + CONF *cnf = NULL; + long eline; + fp = fopen("/somepath/app.cnf", "r"); + if (fp == NULL) { + fprintf(stderr, "Error opening configuration file\n"); + /* Other missing configuration file behaviour */ + } else { + cnf = NCONF_new(NULL); + if (NCONF_load_fp(cnf, fp, &eline) == 0) { + fprintf(stderr, "Error on line %ld of configuration file\n", eline); + ERR_print_errors_fp(stderr); + /* Other malformed configuration file behaviour */ + } else if (CONF_modules_load(cnf, "appname", 0) <= 0) { + fprintf(stderr, "Error configuring application\n"); + ERR_print_errors_fp(stderr); + /* Other configuration error behaviour */ + } + fclose(fp); + NCONF_free(cnf); + } + +=head1 RETURN VALUES These functions return 1 for success and a zero or negative value for failure. If module errors are not ignored the return code will reflect the |