Commit 7c60a968 authored by Dr. Matthias St. Pierre's avatar Dr. Matthias St. Pierre
Browse files

d2i_X509.pod: clarify usage of the 'pp' function parameter 



The 'pp' function parameters of d2i_TYPE() and i2d_TYPE() are referenced
in the DESCRIPTION section as 'in' resp. 'out'. This commit renames the
references to 'ppin' resp. 'ppout' and adds an explaining sentence.

Reviewed-by: default avatarRich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5365)
parent 6e99ae58

doc/man3/d2i_X509.pod

+11 −9
Original line number Diff line number Diff line
@@ -364,11 +364,11 @@ i2d_X509_VAL, 


=for comment generic



 TYPE *d2i_TYPE(TYPE **a, unsigned char **pp, long length);

 TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length);

 TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a);

 TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a);



 int i2d_TYPE(TYPE *a, unsigned char **pp);

 int i2d_TYPE(TYPE *a, unsigned char **ppout);

 int i2d_TYPE_fp(FILE *fp, TYPE *a);

 int i2d_TYPE_bio(BIO *bp, TYPE *a);
@@ -376,14 +376,16 @@ i2d_X509_VAL, 


In the description here, I<TYPE> is used a placeholder

for any of the OpenSSL datatypes, such as I<X509_CRL>.

The function parameters I<ppin> and I<ppout> are generally

either both named I<pp> in the headers, or I<in> and I<out>.



These functions convert OpenSSL objects to and from their ASN.1/DER

encoding.  Unlike the C structures which can have pointers to sub-objects

within, the DER is a serialized encoding, suitable for sending over the

network, writing to a file, and so on.



d2i_TYPE() attempts to decode B<len> bytes at B<*in>. If successful a

pointer to the B<TYPE> structure is returned and B<*in> is incremented to

d2i_TYPE() attempts to decode B<len> bytes at B<*ppin>. If successful a

pointer to the B<TYPE> structure is returned and B<*ppin> is incremented to

the byte following the parsed data.  If B<a> is not B<NULL> then a pointer

to the returned structure is also written to B<*a>.  If an error occurred

then B<NULL> is returned.
@@ -401,13 +403,13 @@ d2i_TYPE_fp() is similar to d2i_TYPE() except it attempts 
to parse data from FILE pointer B<fp>.



i2d_TYPE() encodes the structure pointed to by B<a> into DER format.

If B<out> is not B<NULL>, it writes the DER encoded data to the buffer

at B<*out>, and increments it to point after the data just written.

If B<ppout> is not B<NULL>, it writes the DER encoded data to the buffer

at B<*ppout>, and increments it to point after the data just written.

If the return value is negative an error occurred, otherwise it

returns the length of the encoded data.



If B<*out> is B<NULL> memory will be allocated for a buffer and the encoded

data written to it. In this case B<*out> is not incremented and it points

If B<*ppout> is B<NULL> memory will be allocated for a buffer and the encoded

data written to it. In this case B<*ppout> is not incremented and it points

to the start of the data just written.



i2d_TYPE_bio() is similar to i2d_TYPE() except it writes
@@ -438,7 +440,7 @@ Therefore any FILE pointers or BIOs should be opened in binary mode. 
Functions such as strlen() will B<not> return the correct length

of the encoded structure.



The ways that B<*in> and B<*out> are incremented after the operation

The ways that B<*ppin> and B<*ppout> are incremented after the operation

can trap the unwary. See the B<WARNINGS> section for some common

errors.

The reason for this-auto increment behaviour is to reflect a typical