diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2000-09-07 00:22:31 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2000-09-07 00:22:31 +0000 |
commit | 47770c4dfb886843df54a4c1d68beebbcbbeecf6 (patch) | |
tree | 3110927c669927784ac171b573e0a0efee922af3 /doc/crypto/BIO_push.pod | |
parent | 7228920ca8c0eca5b11cea9c5ba6b743883356dc (diff) |
Some BIO docs, incomplete, more to follow.
Hmmm I didn't realise BIO_pop() did that:
isn't source wonderful?
Diffstat (limited to 'doc/crypto/BIO_push.pod')
-rw-r--r-- | doc/crypto/BIO_push.pod | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/doc/crypto/BIO_push.pod b/doc/crypto/BIO_push.pod new file mode 100644 index 0000000000..5d0d39e4f0 --- /dev/null +++ b/doc/crypto/BIO_push.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + + BIO_push, BIO_pop - add and remove BIOs from a chain. + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + BIO * BIO_push(BIO *b,BIO *append); + BIO * BIO_pop(BIO *b); + +=head1 DESCRIPTION + +The BIO_push() function appends the BIO B<append> to B<b>, it returns +B<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. + +=head1 NOTES + +The names of these functions are perhaps a little misleading. BIO_push() +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. + +=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. + +If the call: + + BIO_push(b64, f); + +is made then the new chain will be B<b64-chain>. 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>. + +It should be noted that reading causes data to pass in the reverse +direction, that is data is read from B<f>, base64 B<decoded> and digested +by B<md1> and B<md2>. If 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. + +=head1 RETURN VALUES + +BIO_push() returns the end of the chain, B<b>. + +BIO_pop() returns the next BIO in the chain, or NULL if there is no next +BIO. + +=head1 SEE ALSO + +TBA |