diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-11-19 20:38:27 +0100 |
---|---|---|
committer | Dr. David von Oheimb <dev@ddvo.net> | 2021-11-26 14:29:02 +0100 |
commit | 7a37fd09a8f3607ed8acf55e03479861595be069 (patch) | |
tree | 645d32dee8a5fb614a7bc0391c73067da9a7d079 /doc | |
parent | 0a10825a009c830125fef94c81d34e41300a24a5 (diff) | |
download | openssl-7a37fd09a8f3607ed8acf55e03479861595be069.tar.gz |
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)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/BIO_push.pod | 53 |
1 files changed, 31 insertions, 22 deletions
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 <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 |