Update documentation for 'gcry_sexp_extract_param'.

* doc/gcrypt.texi (gcry_sexp_extract_param): Mention that all MIPs
must be set to NULL first, and document how the function behaves in
case of errors.
* src/sexp.c (_gcry_sexp_extract_param): Likewise.
* src/gcrypt.h.in (gcry_sexp_extract_param): Copy the comment from
'_gcry_sexp_extract_param'.

Signed-off-by: Justus Winter <justus@g10code.com>

3 files changed, 61 insertions, 10 deletions

diff --git a/doc/gcrypt.texi b/doc/gcrypt.texi
index 23b1f790..3265a706 100644
--- a/doc/gcrypt.texi
+++ b/doc/gcrypt.texi
@@ -4336,8 +4336,10 @@ In general parameter names are single letters.  To use a string for a
 parameter name, enclose the name in single quotes.
 
 Unless in buffer descriptor mode for each parameter name a pointer to
-an @code{gcry_mpi_t} variable is expected finally followed by a @code{NULL}.
-For example
+an @code{gcry_mpi_t} variable is expected that must be set to
+@code{NULL} prior to invoking this function, and finally a @code{NULL}
+is expected.  For example
+
 @example
   _gcry_sexp_extract_param (key, NULL, "n/x+e d-'foo'",
                             &mpi_n, &mpi_x, &mpi_e, &mpi_foo, NULL)
@@ -4366,8 +4368,11 @@ number of bytes copied to that buffer; in case the buffer is too
 small, the function immediately returns with an error code (and
 @var{len} is set to 0).
 
-The function returns NULL on success.  On error an error code is
-returned and the passed MPIs are either unchanged or set to NULL.
+The function returns 0 on success.  On error an error code is
+returned, all passed MPIs that might have been allocated up to this
+point are deallocated and set to @code{NULL}, and all passed buffers
+are either truncated if the caller supplied the buffer, or deallocated
+if the function allocated the buffer.
 @end deftypefun
 
 
diff --git a/src/gcrypt.h.in b/src/gcrypt.h.in
index f48f04fb..797da2e2 100644
--- a/src/gcrypt.h.in
+++ b/src/gcrypt.h.in
@@ -473,8 +473,51 @@ char *gcry_sexp_nth_string (gcry_sexp_t list, int number);
    value can't be converted to an MPI, `NULL' is returned.  */
 gcry_mpi_t gcry_sexp_nth_mpi (gcry_sexp_t list, int number, int mpifmt);
 
-/* Convenience function to extract parameters from an S-expression
- * using a list of single letter parameters.  */
+/* Extract MPIs from an s-expression using a list of parameters.  The
+ * names of these parameters are given by the string LIST.  Some
+ * special characters may be given to control the conversion:
+ *
+ *    + :: Switch to unsigned integer format (default).
+ *    - :: Switch to standard signed format.
+ *    / :: Switch to opaque format.
+ *    & :: Switch to buffer descriptor mode - see below.
+ *    ? :: The previous parameter is optional.
+ *
+ * In general parameter names are single letters.  To use a string for
+ * a parameter name, enclose the name in single quotes.
+ *
+ * Unless in gcry_buffer_t mode for each parameter name a pointer to
+ * an MPI variable is expected that must be set to NULL prior to
+ * invoking this function, and finally a NULL is expected.  Example:
+ *
+ *   _gcry_sexp_extract_param (key, NULL, "n/x+ed",
+ *                             &mpi_n, &mpi_x, &mpi_e, NULL)
+ *
+ * This stores the parameter "N" from KEY as an unsigned MPI into
+ * MPI_N, the parameter "X" as an opaque MPI into MPI_X, and the
+ * parameter "E" again as an unsigned MPI into MPI_E.
+ *
+ * If in buffer descriptor mode a pointer to gcry_buffer_t descriptor
+ * is expected instead of a pointer to an MPI.  The caller may use two
+ * different operation modes: If the DATA field of the provided buffer
+ * descriptor is NULL, the function allocates a new buffer and stores
+ * it at DATA; the other fields are set accordingly with OFF being 0.
+ * If DATA is not NULL, the function assumes that DATA, SIZE, and OFF
+ * describe a buffer where to but the data; on return the LEN field
+ * receives the number of bytes copied to that buffer; if the buffer
+ * is too small, the function immediately returns with an error code
+ * (and LEN set to 0).
+ *
+ * PATH is an optional string used to locate a token.  The exclamation
+ * mark separated tokens are used to via gcry_sexp_find_token to find
+ * a start point inside SEXP.
+ *
+ * The function returns 0 on success.  On error an error code is
+ * returned, all passed MPIs that might have been allocated up to this
+ * point are deallocated and set to NULL, and all passed buffers are
+ * either truncated if the caller supplied the buffer, or deallocated
+ * if the function allocated the buffer.
+ */
 gpg_error_t gcry_sexp_extract_param (gcry_sexp_t sexp,
                                      const char *path,
                                      const char *list,
diff --git a/src/sexp.c b/src/sexp.c
index d063962c..636f9220 100644
--- a/src/sexp.c
+++ b/src/sexp.c
@@ -2183,8 +2183,8 @@ _gcry_sexp_canon_len (const unsigned char *buffer, size_t length,
  * a parameter name, enclose the name in single quotes.
  *
  * Unless in gcry_buffer_t mode for each parameter name a pointer to
- * an MPI variable is expected and finally a NULL is expected.
- * Example:
+ * an MPI variable is expected that must be set to NULL prior to
+ * invoking this function, and finally a NULL is expected.  Example:
  *
  *   _gcry_sexp_extract_param (key, NULL, "n/x+ed",
  *                             &mpi_n, &mpi_x, &mpi_e, NULL)
@@ -2208,8 +2208,11 @@ _gcry_sexp_canon_len (const unsigned char *buffer, size_t length,
  * mark separated tokens are used to via gcry_sexp_find_token to find
  * a start point inside SEXP.
  *
- * The function returns NULL on success.  On error an error code is
- * returned and the passed MPIs are either unchanged or set to NULL.
+ * The function returns 0 on success.  On error an error code is
+ * returned, all passed MPIs that might have been allocated up to this
+ * point are deallocated and set to NULL, and all passed buffers are
+ * either truncated if the caller supplied the buffer, or deallocated
+ * if the function allocated the buffer.
  */
 gpg_err_code_t
 _gcry_sexp_vextract_param (gcry_sexp_t sexp, const char *path,