constify *_dup() and *i2d_*() and related functions as far as possible, introducing...

[openssl.git] / doc / man3 / d2i_X509.pod

diff --git a/doc/man3/d2i_X509.pod b/doc/man3/d2i_X509.pod
index 8096b39b1e981ce0bd407102faff66119497b376..cad78773964a5b3ad1a8e60da3ef912a5e0a3498 100644 (file)
--- a/doc/man3/d2i_X509.pod
+++ b/doc/man3/d2i_X509.pod
@@ -364,26 +364,31 @@ 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(const TYPE *a, unsigned char **ppout);
+ int i2d_TYPE(TYPE *a, unsigned char **ppout);
+ int i2d_TYPE_fp(FILE *fp, const TYPE *a);
  int i2d_TYPE_fp(FILE *fp, TYPE *a);
+ int i2d_TYPE_bio(BIO *bp, const TYPE *a);
  int i2d_TYPE_bio(BIO *bp, TYPE *a);
 
 =head1 DESCRIPTION
 
 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 +406,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 +443,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
@@ -459,7 +464,7 @@ Represents a PKCS#3 DH parameters structure.
 
 =item B<DHparamx>
 
-Represents a ANSI X9.42 DH parameters structure.
+Represents an ANSI X9.42 DH parameters structure.
 
 =item B<DSA_PUBKEY>
 
@@ -494,6 +499,19 @@ Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7.
 
 =back
 
+=head1 RETURN VALUES
+
+d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
+or B<NULL> if an error occurs.  If the "reuse" capability has been used with
+a valid structure being passed in via B<a>, then the object is not freed in
+the event of error but may be in a potentially invalid or inconsistent state.
+
+i2d_TYPE() returns the number of bytes successfully encoded or a negative
+value if an error occurs.
+
+i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
+occurs.
+
 =head1 EXAMPLES
 
 Allocate and encode the DER encoding of an X509 structure:
@@ -584,24 +602,11 @@ structure has been modified after deserialization or previous
 serialization. This is because some objects cache the encoding for
 efficiency reasons.
 
-=head1 RETURN VALUES
-
-d2i_TYPE(), d2i_TYPE_bio() and d2i_TYPE_fp() return a valid B<TYPE> structure
-or B<NULL> if an error occurs.  If the "reuse" capability has been used with
-a valid structure being passed in via B<a>, then the object is not freed in
-the event of error but may be in a potentially invalid or inconsistent state.
-
-i2d_TYPE() returns the number of bytes successfully encoded or a negative
-value if an error occurs.
-
-i2d_TYPE_bio() and i2d_TYPE_fp() return 1 for success and 0 if an error
-occurs.
-
 =head1 COPYRIGHT
 
 Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved.
 
-Licensed under the OpenSSL license (the "License").  You may not use
+Licensed under the Apache License 2.0 (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
 in the file LICENSE in the source distribution or at
 L<https://www.openssl.org/source/license.html>.