Modify ossl_method_store_add() to handle reference counting

[thirdparty/openssl.git] / doc / internal / man3 / OSSL_METHOD_STORE.pod

diff --git a/doc/internal/man3/OSSL_METHOD_STORE.pod b/doc/internal/man3/OSSL_METHOD_STORE.pod
index 47f4194d1c4ae6c8c975ef266cf7f764d589a517..be439f15b509129a350e486f7416387fdbd85165 100644 (file)
--- a/doc/internal/man3/OSSL_METHOD_STORE.pod
+++ b/doc/internal/man3/OSSL_METHOD_STORE.pod
@@ -2,10 +2,11 @@
 
 =head1 NAME
 
-ossl_method_store_new, ossl_method_store_free, ossl_method_store_init,
-ossl_method_store_cleanup, ossl_method_store_add, ossl_method_store_remove,
-ossl_method_store_fetch, ossl_method_store_set_global_properties,
-ossl_method_store_cache_get and ossl_method_store_cache_set
+OSSL_METHOD_STORE, ossl_method_store_new, ossl_method_store_free,
+ossl_method_store_init, ossl_method_store_cleanup,
+ossl_method_store_add, ossl_method_store_remove, ossl_method_store_fetch,
+ossl_method_store_set_global_properties,
+ossl_method_store_cache_get, ossl_method_store_cache_set
 - implementation method store and query
 
 =head1 SYNOPSIS
@@ -14,13 +15,14 @@ ossl_method_store_cache_get and ossl_method_store_cache_set
 
  typedef struct ossl_method_store_st OSSL_METHOD_STORE;
 
- OSSL_METHOD_STORE *ossl_method_store_new(void);
+ OSSL_METHOD_STORE *ossl_method_store_new(OPENSSL_CTX *ctx);
  void ossl_method_store_free(OSSL_METHOD_STORE *store);
- int ossl_method_store_init(void);
- void ossl_method_store_cleanup(void);
+ int ossl_method_store_init(OPENSSL_CTX *ctx);
+ void ossl_method_store_cleanup(OPENSSL_CTX *ctx);
  int ossl_method_store_add(OSSL_METHOD_STORE *store,
-                           int nid, const char *properties,
-                           void *method, void (*method_destruct)(void *));
+                           int nid, const char *properties, void *method,
+                           int (*method_up_ref)(void *),
+                           void (*method_destruct)(void *));
  int ossl_method_store_remove(OSSL_METHOD_STORE *store,
                               int nid, const void *method);
  int ossl_method_store_fetch(OSSL_METHOD_STORE *store,
@@ -50,19 +52,24 @@ separately (see L</Cache Functions> below).
 
 =head2 Store Functions
 
-ossl_method_store_init() initialises the method store subsystem.
+ossl_method_store_init() initialises the method store subsystem in the scope of
+the library context B<ctx>.
 
 ossl_method_store_cleanup() cleans up and shuts down the implementation method
-store subsystem.
+store subsystem in the scope of the library context B<ctx>.
 
-ossl_method_store_new() create a new empty method store.
+ossl_method_store_new() create a new empty method store using the supplied
+B<ctx> to allow access to the required underlying property data.
 
 ossl_method_store_free() frees resources allocated to B<store>.
 
 ossl_method_store_add() adds the B<method> to the B<store> as an instance of an
 algorithm indicated by B<nid> and the property definition B<properties>.
-The optional B<method_destruct> function is called when B<method> is being
-released from B<store>.
+If the B<method_up_ref> function is given, it's called to increment the
+reference count of the method.
+If the B<method_destruct> function is given, it's called when this function
+fails to add the method to the store, or later on when it is being released from
+the B<store>.
 
 ossl_method_store_remove() removes the B<method> identified by B<nid> from the
 B<store>.
@@ -100,7 +107,7 @@ ossl_method_store_free() and ossl_method_store_cleanup() do not return values.
 
 =head1 HISTORY
 
-This functionality was added to OpenSSL 3.0.0.
+This functionality was added to OpenSSL 3.0.
 
 =head1 COPYRIGHT