Correct some OSSL_PARAM documentation
[openssl.git] / doc / internal / man3 / ossl_param_bld_init.pod
index ca206c7..a65aa8b 100644 (file)
@@ -2,15 +2,15 @@
 
 =head1 NAME
 
-ossl_param_build_init,
-ossl_param_build_to_param, ossl_param_build_push_int,
-ossl_param_build_push_uint, ossl_param_build_push_long,
-ossl_param_build_push_ulong, ossl_param_build_push_int32,
-ossl_param_build_push_uint32, ossl_param_build_push_int64,
-ossl_param_build_push_uint64, ossl_param_build_push_size_t,
-ossl_param_build_push_double, ossl_param_build_push_BN,
-ossl_param_build_push_utf8_string, ossl_param_build_push_utf8_ptr,
-ossl_param_build_push_octet_string, ossl_param_build_push_octet_ptr
+ossl_param_bld_init,
+ossl_param_bld_to_param, ossl_param_bld_push_int,
+ossl_param_bld_push_uint, ossl_param_bld_push_long,
+ossl_param_bld_push_ulong, ossl_param_bld_push_int32,
+ossl_param_bld_push_uint32, ossl_param_bld_push_int64,
+ossl_param_bld_push_uint64, ossl_param_bld_push_size_t,
+ossl_param_bld_push_double, ossl_param_bld_push_BN,
+ossl_param_bld_push_utf8_string, ossl_param_bld_push_utf8_ptr,
+ossl_param_bld_push_octet_string, ossl_param_bld_push_octet_ptr
 - functions to assist in the creation of OSSL_PARAM arrays
 
 =head1 SYNOPSIS
@@ -22,25 +22,25 @@ ossl_param_build_push_octet_string, ossl_param_build_push_octet_ptr
  #define OSSL_PARAM_BLD_MAX 10
  typedef struct { ... } OSSL_PARAM_BLD;
 
- void ossl_param_build_init(OSSL_PARAM_BLD *bld);
- OSSL_PARAM *ossl_param_build_to_param(OSSL_PARAM_BLD *bld, void **secure);
- OSSL_PARAM *ossl_param_build_to_param_ex(OSSL_PARAM_BLD *bld,
+ void ossl_param_bld_init(OSSL_PARAM_BLD *bld);
+ OSSL_PARAM *ossl_param_bld_to_param(OSSL_PARAM_BLD *bld, void **secure);
+ OSSL_PARAM *ossl_param_bld_to_param_ex(OSSL_PARAM_BLD *bld,
                                         OSSL_PARAM *params, size_t param_n,
                                         void *data, size_t data_n,
                                         void *secure, size_t secure_n);
 
- int ossl_param_build_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
+ int ossl_param_bld_push_TYPE(OSSL_PARAM_BLD *bld, const char *key, TYPE val);
 
- int ossl_param_build_push_BN(OSSL_PARAM_BLD *bld, const char *key,
+ int ossl_param_bld_push_BN(OSSL_PARAM_BLD *bld, const char *key,
                             const BIGNUM *bn);
 
- int ossl_param_build_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
+ int ossl_param_bld_push_utf8_string(OSSL_PARAM_BLD *bld, const char *key,
                                      char *buf, size_t bsize);
- int ossl_param_build_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
+ int ossl_param_bld_push_utf8_ptr(OSSL_PARAM_BLD *bld, const char *key,
                                   char *buf, size_t bsize);
- int ossl_param_build_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
+ int ossl_param_bld_push_octet_string(OSSL_PARAM_BLD *bld, const char *key,
                                       void *buf, size_t bsize);
- int ossl_param_build_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
+ int ossl_param_bld_push_octet_ptr(OSSL_PARAM_BLD *bld, const char *key,
                                    void *buf, size_t bsize);
 
 
@@ -49,11 +49,11 @@ ossl_param_build_push_octet_string, ossl_param_build_push_octet_ptr
 A collection of utility functions that simplify the creation of OSSL_PARAM
 arrays.  The B<TYPE> names are as per L<OSSL_PARAM_int(3)>.
 
-ossl_param_build_init() initialises the OSSL_PARAM_BLD structure so that values
+ossl_param_bld_init() initialises the OSSL_PARAM_BLD structure so that values
 can be added.
 Any existing values are cleared.
 
-ossl_param_build_to_param() converts a built up OSSL_PARAM_BLD structure
+ossl_param_bld_to_param() converts a built up OSSL_PARAM_BLD structure
 B<bld> into an allocated OSSL_PARAM array.
 The pointer referenced by the B<secure> argument is set to point to an
 allocated block of secure memory if required and to NULL it not. 
@@ -61,7 +61,7 @@ The OSSL_PARAM array and all associated storage can be freed by calling
 OPENSSL_free() with the functions return value and OPENSSL_secure_free()
 with the pointer referenced by B<secure>.
 
-ossl_param_build_to_param_ex() behaves like ossl_param_build_to_param(), except that
+ossl_param_bld_to_param_ex() behaves like ossl_param_bld_to_param(), except that
 no additional memory is allocated.
 An OSSL_PARAM array of at least B<param_n> elements is passed in as B<params>.
 The auxiliary storage for the parameters is a block of memory pointed to
@@ -69,46 +69,46 @@ by B<data> of at least B<data_n> bytes in size.
 If required, secure memory for private BIGNUMs should be pointed to by
 B<secure> of at least B<secure_n> bytes in size.
 
-ossl_param_build_push_TYPE() are a series of functions which will create
+ossl_param_bld_push_TYPE() are a series of functions which will create
 OSSL_PARAM objects of the specified size and correct type for the B<val>
 argument.
 B<val> is stored by value and an expression or auto variable can be used.
 
-ossl_param_build_push_BN() is a function that will create an OSSL_PARAM object
+ossl_param_bld_push_BN() is a function that will create an OSSL_PARAM object
 that holds the specified BIGNUM B<bn>.
 If B<bn> is marked as being securely allocated, the secure flag is
 set in the OSSL_PARAM_BLD structure.
 The B<bn> argument is stored by reference and the underlying BIGNUM object
-must exist until after ossl_param_build_to_param() has been called.
+must exist until after ossl_param_bld_to_param() has been called.
 
-ossl_param_build_push_utf8_string() is a function that will create an OSSL_PARAM
+ossl_param_bld_push_utf8_string() is a function that will create an OSSL_PARAM
 object that references the UTF8 string specified by B<buf>.
 If the length of the string, B<bsize>, is zero then it will be calculated.
 The string that B<buf> points to is stored by reference and must remain in
-scope until after ossl_param_build_to_param() has been called.
+scope until after ossl_param_bld_to_param() has been called.
 
-ossl_param_build_push_octet_string() is a function that will create an OSSL_PARAM
+ossl_param_bld_push_octet_string() is a function that will create an OSSL_PARAM
 object that references the octet string specified by B<buf> and <bsize>.
 The memory that B<buf> points to is stored by reference and must remain in
-scope until after ossl_param_build_to_param() has been called.
+scope until after ossl_param_bld_to_param() has been called.
 
-ossl_param_build_push_utf8_ptr() is a function that will create an OSSL_PARAM
+ossl_param_bld_push_utf8_ptr() is a function that will create an OSSL_PARAM
 object that references the UTF8 string specified by B<buf>.
 If the length of the string, B<bsize>, is zero then it will be calculated.
 The string B<buf> points to is stored by reference and must remain in
 scope until the OSSL_PARAM array is freed.
 
-ossl_param_build_push_octet_ptr() is a function that will create an OSSL_PARAM
+ossl_param_bld_push_octet_ptr() is a function that will create an OSSL_PARAM
 object that references the octet string specified by B<buf>.
 The memory B<buf> points to is stored by reference and must remain in
 scope until the OSSL_PARAM array is freed.
 
 =head1 RETURN VALUES
 
-ossl_param_build_to_param() and ossl_param_bld_to_param_ex() return the
+ossl_param_bld_to_param() and ossl_param_bld_to_param_ex() return the
 allocated OSSL_PARAM array, or NULL on error.
 
-All of the ossl_param_build_push_TYPE functions return 1 on success and 0
+All of the ossl_param_bld_push_TYPE functions return 1 on success and 0
 on error.
 
 =head1 NOTES
@@ -139,13 +139,13 @@ private key.
     OSSL_PARAM *params;
     void *secure;
 
-    ossl_param_build_init(&bld, &secure);
-    if (!ossl_param_build_push_BN(&bld, "p", p)
-        || !ossl_param_build_push_BN(&bld, "q", q)
-        || !ossl_param_build_push_uint(&bld, "e", e)
-        || !ossl_param_build_push_BN(&bld, "n", n)
-        || !ossl_param_build_push_BN(&bld, "d", d)
-        || (params = ossl_param_build_to_param(&bld)) == NULL)
+    ossl_param_bld_init(&bld, &secure);
+    if (!ossl_param_bld_push_BN(&bld, "p", p)
+        || !ossl_param_bld_push_BN(&bld, "q", q)
+        || !ossl_param_bld_push_uint(&bld, "e", e)
+        || !ossl_param_bld_push_BN(&bld, "n", n)
+        || !ossl_param_bld_push_BN(&bld, "d", d)
+        || (params = ossl_param_bld_to_param(&bld)) == NULL)
         goto err;
     /* Use params */
     ...
@@ -161,10 +161,10 @@ public key.
     OSSL_PARAM *params;
     void *secure;
 
-    ossl_param_build_init(&bld, &secure);
-    if (!ossl_param_build_push_BN(&bld, "n", n)
-        || !ossl_param_build_push_BN(&bld, "d", d)
-        || (params = ossl_param_build_to_param(&bld)) == NULL)
+    ossl_param_bld_init(&bld, &secure);
+    if (!ossl_param_bld_push_BN(&bld, "n", n)
+        || !ossl_param_bld_push_BN(&bld, "d", d)
+        || (params = ossl_param_bld_to_param(&bld)) == NULL)
         goto err;
     /* Use params */
     ...