From 47770c4dfb886843df54a4c1d68beebbcbbeecf6 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Thu, 7 Sep 2000 00:22:31 +0000 Subject: [PATCH] Some BIO docs, incomplete, more to follow. Hmmm I didn't realise BIO_pop() did that: isn't source wonderful? --- doc/crypto/BIO_new.pod | 65 ++++++++++++++++++++++++++++++++++++++ doc/crypto/BIO_push.pod | 69 +++++++++++++++++++++++++++++++++++++++++ doc/crypto/bio.pod | 42 +++++++++++++++++++++++++ 3 files changed, 176 insertions(+) create mode 100644 doc/crypto/BIO_new.pod create mode 100644 doc/crypto/BIO_push.pod create mode 100644 doc/crypto/bio.pod diff --git a/doc/crypto/BIO_new.pod b/doc/crypto/BIO_new.pod new file mode 100644 index 0000000000..3c8f947da3 --- /dev/null +++ b/doc/crypto/BIO_new.pod @@ -0,0 +1,65 @@ +=pod + +=head1 NAME + + BIO_new, BIO_set, BIO_free, BIO_vfree, BIO_free_all - BIO allocation and freeing functions + +=head1 SYNOPSIS + + #include + + BIO * BIO_new(BIO_METHOD *type); + int BIO_set(BIO *a,BIO_METHOD *type); + int BIO_free(BIO *a); + void BIO_vfree(BIO *a); + void BIO_free_all(BIO *a); + +=head1 DESCRIPTION + +The BIO_new() function returns a new BIO using method B. + +BIO_set() sets the method of an already existing BIO. + +BIO_free() frees up a single BIO, BIO_vfree() also frees up a single BIO +but it does not return a value. Calling BIO_free() may also have some effect +on the underlying I/O structure, for example it may close the file being +referred to under certain circumstances. For more details see the individual +BIO_METHOD descriptions. + +BIO_free_all() frees up an entire BIO chain, it does not halt if an error +occurs freeing up an individual BIO in the chain. + +=head1 RETURN VALUES + +BIO_new() returns a newly created BIO or NULL if the call fails. + +BIO_set(), BIO_free() return 1 for success and 0 for failure. + +BIO_free_all() and BIO_vfree() do not return values. + +=head1 NOTES + +Some BIOs (such as memory BIOs) can be used immediately after calling +BIO_new(). Others (such as file BIOs) need some additional initialisation, +and frequently a utility function exists to create and initialize such BIOs. + +If BIO_free() is called on a BIO chain it will only free one BIO resulting +in a memory leak. + +Calling BIO_free_all() a single BIO has the same effect as calling BIO_free() +on it other than the discarded return value. + +Normally the B argument is supplied by a function which returns a +pointer to a BIO_METHOD. There is a naming convention for such functions: +a source/sink BIO is normally called BIO_s_*() and a filter BIO +BIO_f_*(); + +=head1 EXAMPLE + +Create a memory BIO: + + BIO *mem = BIO_new(BIO_s_mem()); + +=head1 SEE ALSO + +TBA 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 + + BIO * BIO_push(BIO *b,BIO *append); + BIO * BIO_pop(BIO *b); + +=head1 DESCRIPTION + +The BIO_push() function appends the BIO B to B, it returns +B. + +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. + +=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 and B are digest BIOs, B is +a base64 BIO and B is a file BIO. + +If the call: + + BIO_push(b64, f); + +is made then the new chain will be B. 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. + +It should be noted that reading causes data to pass in the reverse +direction, that is data is read from B, base64 B and digested +by B and B. If 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. + +=head1 RETURN VALUES + +BIO_push() returns the end of the chain, B. + +BIO_pop() returns the next BIO in the chain, or NULL if there is no next +BIO. + +=head1 SEE ALSO + +TBA diff --git a/doc/crypto/bio.pod b/doc/crypto/bio.pod new file mode 100644 index 0000000000..d86ce4bc00 --- /dev/null +++ b/doc/crypto/bio.pod @@ -0,0 +1,42 @@ +=pod + +=head1 NAME + +bio - I/O abstraction + +=head1 SYNOPSIS + + #include + +TBA + + +=head1 DESCRIPTION + +A BIO is an I/O abstraction, it hides many of the underlying I/O +details from an application. If an application uses a BIO for its +I/O it can transparently handle SSL connections, unencrypted network +connections and file I/O. + +There are two type of BIO, a source/sink BIO and a filter BIO. + +As its name implies a source/sink BIO is a source or sink of data, +examples include a socket BIO and a file BIO. + +A filter BIO takes data from one BIO and passes it through to +another, or the application. The data may be left unmodified (for +example a message digest BIO) or translated (for example an +encryption BIO). The effect of a filter BIO may change according +to the I/O operation it is performing: for example an encryption +BIO will encrypt data if it is being written to and decrypt data +if it is being read from. + +BIOs can be joined together to form a chain (a single BIO is a chain +with one component). A chain normally consist of one source/sink +BIO and one or more filter BIOs. Data read from or written to the +end BIO then traverses the chain to the end (normally a source/sink +BIO). + +=head1 SEE ALSO + +TBA -- 2.25.1