From 7e424b54b7d164149a65660013bd1943592ac4e6 Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Fri, 19 Nov 2021 20:38:27 +0100 Subject: BIO_push.pod: fix confusing text and add details on corner cases Reviewed-by: Paul Dale Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/17086) (cherry picked from commit 7a37fd09a8f3607ed8acf55e03479861595be069) --- doc/man3/BIO_push.pod | 53 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 31 insertions(+), 22 deletions(-) (limited to 'doc/man3/BIO_push.pod') diff --git a/doc/man3/BIO_push.pod b/doc/man3/BIO_push.pod index a9a1f84b5d..84ce3f042d 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 - 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 to B, it returns -B. +BIO_push() pushes I on I. +If I is NULL the function does nothing and returns I. +Otherwise it prepends I, which may be a single BIO or a chain of BIOs, +to I (unless I is NULL). +It then makes a control call on I and returns I. -BIO_pop() removes the BIO 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 from any chain is is part of. +If I is NULL the function does nothing and returns NULL. +Otherwise it makes a control call on I 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. The new chain may include some of the same BIOs from the old chain +by I. 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. +BIO_push() returns the head of the chain, +which usually is I, or I if I 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 and B are digest BIOs, B is -a base64 BIO and B is a file BIO. +For these examples suppose I and I are digest BIOs, +I is a base64 BIO and I is a file BIO. If the call: BIO_push(b64, f); -is made then the new chain will be B. After making the calls +is made then the new chain will be I. After making the calls BIO_push(md2, b64); BIO_push(md1, md2); -the new chain is B. Data written to B will be digested -by B and B, B encoded and written to B. +the new chain is I. Data written to I will be digested +by I and I, base64 encoded, and finally written to I. It should be noted that reading causes data to pass in the reverse -direction, that is data is read from B, B decoded and digested -by B and B. If the call: +direction, that is data is read from I, base64 decoded, +and digested by I and then I. + +The call: BIO_pop(md2); -The call will return B and the new chain will be B data can -be written to B as before. +will return I and the new chain will be I. +Data can be written to and read from I as before, +except that I will no more be applied. =head1 SEE ALSO -- cgit v1.2.3