Commit 1fb2993d authored by Benjamin Kaduk's avatar Benjamin Kaduk Committed by Benjamin Kaduk
Browse files

Catch up to the removal of OSSL_STORE_open_file() 



Remove references to it in documentation.

Unfortunately, it is too late to renumber symbols in libcrypto.num
and avoid the NOEXIST entry there.

Reviewed-by: default avatarRichard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3860)
parent baa77e07

doc/man3/OSSL_STORE_INFO.pod

+4 −4
Original line number Diff line number Diff line
@@ -117,10 +117,10 @@ used by the application to get the objects in that file. 
This can be applied to all schemes that can somehow support a listing

of object URIs.



For C<file:> URIs that are used without the explicit scheme, or paths

given to L<OSSL_STORE_open_file(3)>, the returned name will be the path of

each object, so if C</foo/bar> was given and that path has the file

C<cookie.pem>, the name C</foo/bar/cookie.pem> will be returned.

For C<file:> URIs that are used without the explicit scheme, the

returned name will be the path of each object, so if C</foo/bar> was

given and that path has the file C<cookie.pem>, the name

C</foo/bar/cookie.pem> will be returned.



At the discretion of the loader that was used to get these names, an

extra description may be attached as well.

doc/man3/OSSL_STORE_open.pod

+4 −16
Original line number Diff line number Diff line
@@ -99,26 +99,14 @@ OSSL_STORE_register_loader(). 


=head1 NOTES



When unsure whether a given string contains a simple file or directory

reference, or if it's a full blown URI, the question is how to figure

that out.

One way is to try OSSL_STORE_open_file() and if that fails, try

OSSL_STORE_open().

The other way is the other way around.

Either way you choose, there are corner cases,

F<file:/foo/bar/cookie.txt> might very will be a simple file reference

on a system that supports the notion of volumes.



This manual won't tell you which way is better, that's up to each

application developer to decide on their own.

However, there are some tools that can be used together with

A string without a scheme prefix (that is, a non-URI string) is

implicitly interpreted as using the F<file:> scheme.



There are some tools that can be used together with

OSSL_STORE_open() to determine if any failure is caused by an unparsable

URI, or if it's a different error (such as memory allocation

failures); if the URI was parsable but the scheme unregistered, the

top error will have the reason C<OSSL_STORE_R_UNREGISTERED_SCHEME>.

If you decide to use OSSL_STORE_open() with OSSL_STORE_open_file() as a

fallback, those reasons can be good tools to decide if the fallback

should be taken or not.



=head1 RETURN VALUES

doc/man7/ossl_store.pod

+0 −4
Original line number Diff line number Diff line
@@ -59,10 +59,6 @@ only). 


=head2 A generic call



 /*

  * There is also a OSSL_STORE_open_file() that can be used for file paths

  * that can't be represented as URIs, such as Windows backslashes

  */

 OSSL_STORE_CTX *ctx = OSSL_STORE_open("file:/foo/bar/data.pem");



 /*

include/openssl/store.h

+1 −2
Original line number Diff line number Diff line
@@ -114,8 +114,7 @@ int OSSL_STORE_close(OSSL_STORE_CTX *ctx); 


/*

 * Functions to generate OSSL_STORE_INFOs, one function for each type we

 * support having in them.  Along with each of them, one macro that

 * can be used to determine what types are supported.

 * support having in them, as well as a generic constructor.

 *

 * In all cases, ownership of the object is transfered to the OSSL_STORE_INFO

 * and will therefore be freed when the OSSL_STORE_INFO is freed.