openssl
/
openssl
mirror of https://github.com/openssl/openssl
1
0
Fork 0
Code Issues Releases Wiki Activity

BIO_push.pod: fix confusing text and add details on corner cases 

Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/17086)
This commit is contained in:
Dr. David von Oheimb 2021-11-19 20:38:27 +01:00 committed by Dr. David von Oheimb
parent 0a10825a00
commit 7a37fd09a8
1 changed files with 31 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
doc/man3/BIO_push.pod
View File

@ -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