diff options
Diffstat (limited to 'doc/man3/BIO_push.pod')
-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 |