doc: document the encoder and decoder name functions

Reviewed-by: Tim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15211)

diff --git a/doc/man3/OSSL_DECODER.pod b/doc/man3/OSSL_DECODER.pod
index 45a97454e9d73d469add2c550136f9f075434947..fed0da27f885b1a1fa55d585444406d61373fa3d 100644 (file)
--- a/doc/man3/OSSL_DECODER.pod
+++ b/doc/man3/OSSL_DECODER.pod
@@ -10,6 +10,7 @@ OSSL_DECODER_provider,
 OSSL_DECODER_properties,
 OSSL_DECODER_is_a,
 OSSL_DECODER_number,
+OSSL_DECODER_name,
 OSSL_DECODER_description,
 OSSL_DECODER_do_all_provided,
 OSSL_DECODER_names_do_all,
@@ -31,6 +32,7 @@ OSSL_DECODER_get_params
  const char *OSSL_DECODER_properties(const OSSL_DECODER *decoder);
  int OSSL_DECODER_is_a(const OSSL_DECODER *decoder, const char *name);
  int OSSL_DECODER_number(const OSSL_DECODER *decoder);
+ const char *OSSL_DECODER_name(const OSSL_DECODER *decoder);
  const char *OSSL_DECODER_description(const OSSL_DECODER *decoder);
  void OSSL_DECODER_do_all_provided(OSSL_LIB_CTX *libctx,
                                    void (*fn)(OSSL_DECODER *decoder, void *arg),
@@ -74,6 +76,8 @@ of an algorithm that's identifiable with I<name>.
 OSSL_DECODER_number() returns the internal dynamic number assigned
 to the given I<decoder>.
 
+OSSL_DECODER_number() returns the name used to fetch the given I<decoder>.
+
 OSSL_DECODER_description() returns a description of the I<decoder>, meant
 for display and human consumption.  The description is at the discretion
 of the I<decoder> implementation.
@@ -113,6 +117,12 @@ otherwise 0.
 
 OSSL_DECODER_number() returns an integer.
 
+OSSL_DECODER_name() returns the algorithm name from the provided
+implementation for the given I<decoder>. Note that the I<decoder> may have
+multiple synonyms associated with it. In this case the first name from the
+algorithm definition is returned. Ownership of the returned string is retained
+by the I<decoder> object and should not be freed by the caller.
+
 OSSL_DECODER_description() returns a pointer to a decription, or NULL if
 there isn't one.
 

diff --git a/doc/man3/OSSL_ENCODER.pod b/doc/man3/OSSL_ENCODER.pod
index abaee0f997965dfaef18eddbeadfb8fa9a70b591..9ad335653e71545e178fa855823df0c1c581fffa 100644 (file)
--- a/doc/man3/OSSL_ENCODER.pod
+++ b/doc/man3/OSSL_ENCODER.pod
@@ -10,6 +10,7 @@ OSSL_ENCODER_provider,
 OSSL_ENCODER_properties,
 OSSL_ENCODER_is_a,
 OSSL_ENCODER_number,
+OSSL_ENCODER_name,
 OSSL_ENCODER_description,
 OSSL_ENCODER_do_all_provided,
 OSSL_ENCODER_names_do_all,
@@ -31,6 +32,7 @@ OSSL_ENCODER_get_params
  const char *OSSL_ENCODER_properties(const OSSL_ENCODER *encoder);
  int OSSL_ENCODER_is_a(const OSSL_ENCODER *encoder, const char *name);
  int OSSL_ENCODER_number(const OSSL_ENCODER *encoder);
+ const char *OSSL_ENCODER_name(const OSSL_ENCODER *encoder);
  const char *OSSL_ENCODER_description(const OSSL_ENCODER *encoder);
  void OSSL_ENCODER_do_all_provided(OSSL_LIB_CTX *libctx,
                                    void (*fn)(OSSL_ENCODER *encoder, void *arg),
@@ -74,6 +76,8 @@ algorithm that's identifiable with I<name>.
 OSSL_ENCODER_number() returns the internal dynamic number assigned to
 the given I<encoder>.
 
+OSSL_ENCODER_number() returns the name used to fetch the given I<encoder>.
+
 OSSL_ENCODER_description() returns a description of the I<loader>, meant
 for display and human consumption.  The description is at the discretion of the
 I<loader> implementation.
@@ -114,6 +118,12 @@ otherwise 0.
 
 OSSL_ENCODER_number() returns an integer.
 
+OSSL_ENCODER_name() returns the algorithm name from the provided
+implementation for the given I<encoder>. Note that the I<encoder> may have
+multiple synonyms associated with it. In this case the first name from the
+algorithm definition is returned. Ownership of the returned string is retained
+by the I<encoder> object and should not be freed by the caller.
+
 OSSL_ENCODER_description() returns a pointer to a decription, or NULL if
 there isn't one.