Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "OSSL_LIB_CTX 3ossl"
way too many mistakes in technical documents.
When a non default library context is in use care should be taken with multi-threaded applications to properly clean up thread local resources before the \s-1OSSL_LIB_CTX\s0 is freed. See OPENSSL_thread_stop_ex\|(3) for more information.
\fBOSSL_LIB_CTX_new() creates a new OpenSSL library context.
\fBOSSL_LIB_CTX_new_from_dispatch() creates a new OpenSSL library context initialised to use callbacks from the \s-1OSSL_DISPATCH\s0 structure. This is primarily useful for provider authors. The handle and dispatch structure arguments passed should be the same ones as passed to a provider's OSSL_provider_init function. Some OpenSSL functions, such as \fBBIO_new_from_core_bio\|(3), require the library context to be created in this way in order to work.
\fBOSSL_LIB_CTX_new_child() is only useful to provider authors and does the same thing as OSSL_LIB_CTX_new_from_dispatch() except that it additionally links the new library context to the application library context. The new library context is a full library context in its own right, but will have all the same providers available to it that are available in the application library context (without having to reload them). If the application loads or unloads providers from the application library context then this will be automatically mirrored in the child library context.
In addition providers that are not loaded in the parent library context can be explicitly loaded into the child library context independently from the parent library context. Providers loaded independently in this way will not be mirrored in the parent library context and will not be affected if the parent library context subsequently loads the same provider.
A provider may call the function OSSL_PROVIDER_load\|(3) with the child library context as required. If the provider already exists due to it being mirrored from the parent library context then it will remain available and its reference count will be increased. If OSSL_PROVIDER_load\|(3) is called in this way then \fBOSSL_PROVIDER_unload\|(3) should be subsequently called to decrement the reference count. OSSL_PROVIDER_unload\|(3) must not be called for a provider in the child library context that did not have an earlier OSSL_PROVIDER_load\|(3) call for that provider in that child library context.
In addition to providers, a child library context will also mirror the default properties (set via EVP_set_default_properties\|(3)) from the parent library context. If EVP_set_default_properties\|(3) is called directly on a child library context then the new properties will override anything from the parent library context and mirroring of the properties will stop.
When OSSL_LIB_CTX_new_child() is called from within the scope of a provider's \fBOSSL_provider_init function the currently initialising provider is not yet available in the application's library context and therefore will similarly not yet be available in the newly constructed child library context. As soon as the \fBOSSL_provider_init function returns then the new provider is available in the application's library context and will be similarly mirrored in the child library context.
\fBOSSL_LIB_CTX_load_config() loads a configuration file using the given ctx. This can be used to associate a library context with providers that are loaded from a configuration.
\fBOSSL_LIB_CTX_free() frees the given ctx, unless it happens to be the default OpenSSL library context.
\fBOSSL_LIB_CTX_get0_global_default() returns a concrete (non \s-1NULL\s0) reference to the global default library context.
\fBOSSL_LIB_CTX_set0_default() sets the default OpenSSL library context to be \fIctx in the current thread. The previous default library context is returned. Care should be taken by the caller to restore the previous default library context with a subsequent call of this function. If ctx is \s-1NULL\s0 then no change is made to the default library context, but a pointer to the current library context is still returned. On a successful call of this function the returned value will always be a concrete (non \s-1NULL\s0) library context.
Care should be taken when changing the default library context and starting async jobs (see ASYNC_start_job\|(3)), as the default library context when the job is started will be used throughout the lifetime of an async job, no matter how the calling thread makes further default library context changes in the mean time. This means that the calling thread must not free the library context that was the default at the start of the async job before that job has finished.
\fBOSSL_LIB_CTX_free() doesn't return any value.
\fBOSSL_LIB_CTX_load_config() returns 1 on success, 0 on error.
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.