[openssl] OpenSSL_1_1_1-stable update

[dev at ddvo.net]

The branch OpenSSL_1_1_1-stable has been updated
       via  791bfd91bcb02ee51bf16b195293daeeccc3d84c (commit)
      from  5f422920c171077d8e8d49ad69632711f1ac7e5a (commit)


- Log -----------------------------------------------------------------
commit 791bfd91bcb02ee51bf16b195293daeeccc3d84c
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date:   Fri Nov 19 20:38:27 2021 +0100

    BIO_push.pod: fix confusing text and add details on corner cases
    
    Reviewed-by: Paul Dale <pauli at openssl.org>
    Reviewed-by: Tomas Mraz <tomas at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/17086)
    
    (cherry picked from commit 7a37fd09a8f3607ed8acf55e03479861595be069)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/BIO_push.pod | 53 ++++++++++++++++++++++++++++++---------------------
 1 file changed, 31 insertions(+), 22 deletions(-)

diff --git a/doc/man3/BIO_push.pod b/doc/man3/BIO_push.pod
index 8b98bee498..e16daafe88 100644
--- a/doc/man3/BIO_push.pod
+++ b/doc/man3/BIO_push.pod
@@ -8,22 +8,27 @@ BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain
 
  #include <openssl/bio.h>
 
- BIO *BIO_push(BIO *b, BIO *append);
+ BIO *BIO_push(BIO *b, BIO *next);
  BIO *BIO_pop(BIO *b);
  void BIO_set_next(BIO *b, BIO *next);
 
 =head1 DESCRIPTION
 
-The BIO_push() function appends the BIO B<append> to B<b>, it returns
-B<b>.
+BIO_push() pushes I<b> on I<next>.
+If I<b> is NULL the function does nothing and returns I<next>.
+Otherwise it prepends I<b>, which may be a single BIO or a chain of BIOs,
+to I<next> (unless I<next> is NULL).
+It then makes a control call on I<b> and returns I<b>.
 
-BIO_pop() removes the BIO B<b> from a chain and returns the next BIO
-in the chain, or NULL if there is no next BIO. The removed BIO then
-becomes a single BIO with no association with the original chain,
-it can thus be freed or attached to a different chain.
+BIO_pop() removes the BIO I<b> from any chain is is part of.
+If I<b> is NULL the function does nothing and returns NULL.
+Otherwise it makes a control call on I<b> and
+returns the next BIO in the chain, or NULL if there is no next BIO.
+The removed BIO becomes a single BIO with no association with
+the original chain, it can thus be freed or be made part of a different chain.
 
 BIO_set_next() replaces the existing next BIO in a chain with the BIO pointed to
-by B<next>. The new chain may include some of the same BIOs from the old chain
+by I<next>. The new chain may include some of the same BIOs from the old chain
 or it may be completely different.
 
 =head1 NOTES
@@ -33,41 +38,45 @@ joins two BIO chains whereas BIO_pop() deletes a single BIO from a chain,
 the deleted BIO does not need to be at the end of a chain.
 
 The process of calling BIO_push() and BIO_pop() on a BIO may have additional
-consequences (a control call is made to the affected BIOs) any effects will
-be noted in the descriptions of individual BIOs.
+consequences (a control call is made to the affected BIOs).
+Any effects will be noted in the descriptions of individual BIOs.
 
 =head1 RETURN VALUES
 
-BIO_push() returns the end of the chain, B<b>.
+BIO_push() returns the head of the chain,
+which usually is I<b>, or I<next> if I<b> is NULL.
 
-BIO_pop() returns the next BIO in the chain, or NULL if there is no next
-BIO.
+BIO_pop() returns the next BIO in the chain,
+or NULL if there is no next BIO.
 
 =head1 EXAMPLES
 
-For these examples suppose B<md1> and B<md2> are digest BIOs, B<b64> is
-a base64 BIO and B<f> is a file BIO.
+For these examples suppose I<md1> and I<md2> are digest BIOs,
+I<b64> is a base64 BIO and I<f> is a file BIO.
 
 If the call:
 
  BIO_push(b64, f);
 
-is made then the new chain will be B<b64-f>. After making the calls
+is made then the new chain will be I<b64-f>. After making the calls
 
  BIO_push(md2, b64);
  BIO_push(md1, md2);
 
-the new chain is B<md1-md2-b64-f>. Data written to B<md1> will be digested
-by B<md1> and B<md2>, B<base64> encoded and written to B<f>.
+the new chain is I<md1-md2-b64-f>. Data written to I<md1> will be digested
+by I<md1> and I<md2>, base64 encoded, and finally written to I<f>.
 
 It should be noted that reading causes data to pass in the reverse
-direction, that is data is read from B<f>, B<base64> decoded and digested
-by B<md2> and B<md1>. If the call:
+direction, that is data is read from I<f>, base64 decoded,
+and digested by I<md2> and then I<md1>.
+
+The call:
 
  BIO_pop(md2);
 
-The call will return B<b64> and the new chain will be B<md1-b64-f> data can
-be written to B<md1> as before.
+will return I<b64> and the new chain will be I<md1-b64-f>.
+Data can be written to and read from I<md1> as before,
+except that I<md2> will no more be applied.
 
 =head1 SEE ALSO