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: Rich Salz <rsalz@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/5365)

diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 8096b39b1e981ce0bd407102faff66119497b376..80c5c9dd6d087be0b3809ec10f144b6ce3d25315 100644 (file)
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -364,11 +364,11 @@ i2d_X509_VAL,
 
 =for comment generic
 
 
 =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);
 
  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);
 
  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>.
 
 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.
 
 
 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.
 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.
 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 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
 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.
 
 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
 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