From: Dr. Stephen Henson <steve@openssl.org>
Date: Sun, 30 Jan 2000 01:39:40 +0000 (+0000)
Subject: Update docs.
X-Git-Tag: OpenSSL_0_9_5beta1~158
X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=15701211b57b63f1f91a9c3781ea91c019b1dc1d;ds=sidebyside

Update docs.
---

diff --git a/doc/crypto/BN_CTX_new.pod b/doc/crypto/BN_CTX_new.pod
index 45c70fd407..37a188e3c3 100644
--- a/doc/crypto/BN_CTX_new.pod
+++ b/doc/crypto/BN_CTX_new.pod
@@ -16,12 +16,12 @@ BN_CTX_new, BN_CTX_init, BN_CTX_free - allocate and free BN_CTX structures
 
 =head1 DESCRIPTION
 
-A B<BN_CTX> is a structure that holds temporary variables used by
-library functions. Thus, it can be avoided to create and destroy
-the temporary B<BIGNUM> objects whenever a library function is
-called.
+A B<BN_CTX> is a structure that holds B<BIGNUM> temporary variables used by
+library functions. Since dynamic memory allocation to create B<BIGNUM>s
+is rather expensive when used in conjunction with repeated subroutine
+calls, the B<BN_CTX> structure is used.
 
-BN_CTX_new() allocated and initializes a B<BN_CTX>
+BN_CTX_new() allocates and initializes a B<BN_CTX>
 structure. BN_CTX_init() initializes an existing uninitialized
 B<BN_CTX>.
 
diff --git a/doc/crypto/BN_zero.pod b/doc/crypto/BN_zero.pod
index 43b6337bae..165fd9a228 100644
--- a/doc/crypto/BN_zero.pod
+++ b/doc/crypto/BN_zero.pod
@@ -39,6 +39,9 @@ BN_value_one() returns the constant.
 
 Someone might change the constant.
 
+If a B<BIGNUM> is equal to 0xffffffffL it can be represented as an
+unsigned long but this value is also returned on error.
+
 =head1 SEE ALSO
 
 L<bn(3)|bn(3)>, L<BN_bn2bin(3)|BN_bn2bin(3)>
diff --git a/doc/crypto/CRYPTO_set_ex_data.pod b/doc/crypto/CRYPTO_set_ex_data.pod
new file mode 100644
index 0000000000..1bd5bed67d
--- /dev/null
+++ b/doc/crypto/CRYPTO_set_ex_data.pod
@@ -0,0 +1,51 @@
+=pod
+
+=head1 NAME
+
+CRYPTO_set_ex_data, CRYPTO_get_ex_data - internal application specific data functions
+
+=head1 SYNOPSIS
+
+ int CRYPTO_set_ex_data(CRYPTO_EX_DATA *r, int idx, void *arg);
+
+ void *CRYPTO_get_ex_data(CRYPTO_EX_DATA *r, int idx);
+
+=head1 DESCRIPTION
+
+Several OpenSSL structures can have application specific data attached to them.
+These functions are used internally by OpenSSL to manipulate application
+specific data attached to a specific structure.
+
+These functions should only be used by applications to manipulate
+B<CRYPTO_EX_DATA> structures passed to the B<new_func()>, B<free_func()> and
+B<dup_func()> callbacks: as passed to B<RSA_get_ex_new_index()> for example.
+
+B<CRYPTO_set_ex_data()> is used to set application specific data, the data is
+supplied in the B<arg> parameter and its precise meaning is up to the
+application.
+
+B<CRYPTO_get_ex_data()> is used to retrieve application specific data. The data
+is returned to the application, this will be the same value as supplied to
+a previous B<CRYPTO_set_ex_data()> call.
+
+=head1 RETURN VALUES
+
+B<CRYPTO_set_ex_data()> returns 1 on success or 0 on failure.
+
+B<CRYPTO_get_ex_data()> returns the application data or 0 on failure. 0 may also
+be valid application data but currently it can only fail if given an invalid B<idx>
+parameter.
+
+On failure an error code can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>.
+
+=head1 SEE ALSO
+
+L<RSA_get_ex_new_index(3)|RSA_get_ex_new_index(3)>,
+L<DSA_get_ex_new_index(3)|DSA_get_ex_new_index(3)>,
+L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>
+
+=head1 HISTORY
+
+CRYPTO_set_ex_data() and CRYPTO_get_ex_data() have been available since SSLeay 0.9.0.
+
+=cut
diff --git a/doc/crypto/RSA_get_ex_new_index.pod b/doc/crypto/RSA_get_ex_new_index.pod
index d0267a2ea1..920dc76325 100644
--- a/doc/crypto/RSA_get_ex_new_index.pod
+++ b/doc/crypto/RSA_get_ex_new_index.pod
@@ -71,7 +71,7 @@ B<new_func()> and B<free_func()> take the same parameters. B<parent> is a
 pointer to the parent RSA structure. B<ptr> is a the application specific data
 (this wont be of much use in B<new_func()>. B<ad> is a pointer to the
 B<CRYPTO_EX_DATA> structure from the parent RSA structure: the functions
-B<CRYPTO_get_ex_data()> and B<CRYPTO_get_ex_data()> can be called to manipulate
+B<CRYPTO_get_ex_data()> and B<CRYPTO_set_ex_data()> can be called to manipulate
 it. The B<idx> parameter is the index: this will be the same value returned by
 B<RSA_get_ex_new_index()> when the functions were initially registered. Finally
 the B<argl> and B<argp> parameters are the values originally passed to the same
@@ -112,7 +112,7 @@ present in the parent RSA structure when it is called.
 
 =head1 SEE ALSO
 
-L<rsa(3)|rsa(3)>
+L<rsa(3)|rsa(3)>, L<CRYPTO_set_ex_data(3)|CRYPTO_set_ex_data(3)>
 
 =head1 HISTORY
 
diff --git a/doc/crypto/bn.pod b/doc/crypto/bn.pod
index 3d4840f095..823561fa8d 100644
--- a/doc/crypto/bn.pod
+++ b/doc/crypto/bn.pod
@@ -144,14 +144,14 @@ The following description is based on the SSLeay documentation:
         int neg;
         } BIGNUM;
 
-The big number is stored in B<d>, a malloc()ed array of B<BN_ULONG>s.
-A B<BN_ULONG> can be either 16, 32 or 64 bits in size, depending on
-the 'number of bits' specified in bn.h.
+The big number is stored in B<d>, a malloc()ed array of B<BN_ULONG>s,
+least significant first. A B<BN_ULONG> can be either 16, 32 or 64 bits
+in size, depending on the 'number of bits' specified in bn.h. 
 
 B<max> is the size of the B<d> array that has been allocated.  B<top>
 is the 'last' entry being used, so for a value of 4, bn.d[0]=4 and
 bn.top=1. B<neg> is 1 if the number is negative.  When a BIGNUM is
-'0', the B<d> field can be NULL and B<top> == 0.  Various routines in
+'0', the B<d> field can be NULL and B<top> == 0. Various routines in
 this library require the use of temporary B<BIGNUM> variables during
 their execution.  Since dynamic memory allocation to create B<BIGNUM>s
 is rather expensive when used in conjunction with repeated subroutine
@@ -166,6 +166,8 @@ temporary B<BIGNUM>s any publicly exported function will use.
         BIGNUM *bn[BN_CTX_NUM];     /* The variables */
         } BN_CTX;
 
+B<tos> is the index of the first unused B<BIGNUM> in the B<bn> array.
+
 =head1 SEE ALSO
 
 L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>,