Add dire warnings about the "reuse" capability of the d2i_* functions.

occurred then B<NULL> is returned. If B<px> is not B<NULL> then the

returned structure is written to B<*px>. If B<*px> is not B<NULL>

then it is assumed that B<*px> contains a valid B<X509>

structure and an attempt is made to reuse it. If the call is

successful B<*in> is incremented to the byte following the

structure and an attempt is made to reuse it. This "reuse" capability is present

for historical compatibility but its use is B<strongly discouraged> (see BUGS

below, and the discussion in the RETURN VALUES section).

If the call is successful B<*in> is incremented to the byte following the

parsed data.

i2d_X509() encodes the structure pointed to by B<x> into DER format.

errors.

The reason for the auto increment behaviour is to reflect a typical

usage of ASN1 functions: after one structure is encoded or decoded

usage of ASN1 functions: after one structure is encoded or decoded    if (a != NULL)

        (*a) = ret;

another will processed after it.

=head1 EXAMPLES

i2d_X509() will not return an error in many versions of OpenSSL,

if mandatory fields are not initialized due to a programming error

then the encoded structure may contain invalid data or omit the

then the encoded structure may contain invalid data or omit the    if (a != NULL)

        (*a) = ret;

fields entirely and will not be parsed by d2i_X509(). This may be

fixed in future so code should not assume that i2d_X509() will

always succeed.

d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure

or B<NULL> if an error occurs. The error code that can be obtained by

L<ERR_get_error(3)|ERR_get_error(3)>. 

L<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used

with a valid X509 structure being passed in via B<px> then the object is not

freed in the event of error but may be in a potentially invalid or inconsistent

state.

i2d_X509() returns the number of bytes successfully encoded or a negative

value if an error occurs. The error code can be obtained by