Catch up to the removal of OSSL_STORE_open_file()

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

diff --git a/doc/man3/OSSL_STORE_open.pod b/doc/man3/OSSL_STORE_open.pod
index b63156a95c5904d02188a5c5fbbc9aa83d08c235..0bc6d5ccfd87ceb3a92501300f42b85e208c0c1e 100644 (file)
--- a/doc/man3/OSSL_STORE_open.pod
+++ b/doc/man3/OSSL_STORE_open.pod
@@ -9,7 +9,7 @@ OSSL_STORE_close - Types and functions to read objects from a URI
 =head1 SYNOPSIS
 
  #include <openssl/store.h>
- 
+
  typedef struct ossl_store_ctx_st OSSL_STORE_CTX;
 
  typedef OSSL_STORE_INFO *(*OSSL_STORE_post_process_info_fn)(OSSL_STORE_INFO *,
@@ -58,8 +58,23 @@ OSSL_STORE_load() to manipulate or drop the value to be returned.
 
 OSSL_STORE_ctrl() takes a B<OSSL_STORE_CTX>, and command number B<cmd> and
 more arguments not specified here.
-The available command numbers and arguments they each take depends on
-the loader that's used and is documented together with that loader.
+The available loader specific command numbers and arguments they each
+take depends on the loader that's used and is documented together with
+that loader.
+
+There are also global controls available:
+
+=over 4
+
+=item B<OSSL_STORE_C_USE_SECMEM>
+
+Controls if the loader should attempt to use secure memory for any
+allocated B<OSSL_STORE_INFO> and its contents.
+This control expects one argument, a pointer to an B<int> that is expected to
+have the value 1 (yes) or 0 (no).
+Any other value is an error.
+
+=back
 
 OSSL_STORE_load() takes a B<OSSL_STORE_CTX>, tries to load the next available
 object and return it wrapped with  B<OSSL_STORE_INFO>.
@@ -69,6 +84,8 @@ of data.
 
 OSSL_STORE_error() takes a B<OSSL_STORE_CTX> and checks if an error occured in
 the last OSSL_STORE_load() call.
+Note that it may still be meaningful to try and load more objects, unless
+OSSL_STORE_eof() shows that the end of data has been reached.
 
 OSSL_STORE_close() takes a B<OSSL_STORE_CTX>, closes the channel that was opened
 by OSSL_STORE_open() and frees all other information that was stored in the
@@ -82,31 +99,24 @@ 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
 
-OSSL_STORE_open() and OSSL_STORE_load() return a pointer to a B<OSSL_STORE_CTX>
-on success, or B<NULL> on failure.
+OSSL_STORE_open() returns a pointer to a B<OSSL_STORE_CTX> on success, or
+B<NULL> on failure.
+
+OSSL_STORE_load() returns a pointer to a B<OSSL_STORE_INFO> on success, or
+B<NULL> on error or when end of data is reached.
+Use OSSL_STORE_error() and OSSL_STORE_eof() to determine the meaning of a
+returned B<NULL>.
 
 OSSL_STORE_eof() returns 1 if the end of data has been reached, otherwise
 0.