The branch master has been updated via 7c60a968ce1a6a8290dd3a9418ae10e06327f424 (commit) from 6e99ae58c8e1b4a41ae376f91affc7992b0738f7 (commit)
- Log ----------------------------------------------------------------- commit 7c60a968ce1a6a8290dd3a9418ae10e06327f424 Author: Dr. Matthias St. Pierre <matthias.st.pie...@ncp-e.com> Date: Wed Feb 14 12:21:26 2018 +0100 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 <rs...@openssl.org> (Merged from https://github.com/openssl/openssl/pull/5365) ----------------------------------------------------------------------- Summary of changes: doc/man3/d2i_X509.pod | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod index 8096b39..80c5c9d 100644 --- a/doc/man3/d2i_X509.pod +++ b/doc/man3/d2i_X509.pod @@ -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 _____ openssl-commits mailing list To unsubscribe: https://mta.openssl.org/mailman/listinfo/openssl-commits