Commit 85556b4d authored by Matt Caswell's avatar Matt Caswell
Browse files

Add documentation for BIO functions 



Add the documentation for new BIO functions added as a result of
making BIO and BIO_METHOD opaque.

Reviewed-by: default avatarRichard Levitte <levitte@openssl.org>
parent 17375525

doc/crypto/BIO_get_data.pod

0 → 100644
+56 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



BIO_set_data, BIO_get_data, BIO_set_init, BIO_get_init, BIO_set_shutdown,

BIO_get_shutdown - functions for managing BIO state information



=head1 SYNOPSIS



 #include <openssl/bio.h>



 void BIO_set_data(BIO *a, void *ptr);

 void *BIO_get_data(BIO *a);

 void BIO_set_init(BIO *a, int init);

 int BIO_get_init(BIO *a);

 void BIO_set_shutdown(BIO *a, int shut);

 int BIO_get_shutdown(BIO *a);



=head1 DESCRIPTION



These functions are mainly useful when implementing a custom BIO.



The BIO_set_data() function associates the custom data pointed to by B<ptr> with

the BIO. This data can subsequently be retrieved via a call to BIO_get_data().

This can be used by custom BIOs for storing implementation specific information.



The BIO_set_init() function sets the value of the BIO's "init" flag to indicate

whether initialisation has been completed for this BIO or not. A non-zero value

indicates that initialisation is complete, whilst zero indicates that it is not.

Often initialisation will complete during initial construction of the BIO. For

some BIOs however, initialisation may not complete until after additional steps

have occurred (for example through calling custom ctrls). The BIO_get_init()

function returns the value of the "init" flag.



The BIO_set_shutdown() and BIO_get_shutdown() functions set and get the state of

this BIO's shutdown (i.e. BIO_CLOSE) flag. If set then the underlying resource

is also closed when the BIO is freed.



=head1 RETURN VALUES



BIO_get_data() returns a pointer to the implementation specific custom data

associated with this BIO, or NULL if none has been set.



BIO_get_init() returns the state of the BIO's init flag.



BIO_get_shutdown() returns the stat of the BIO's shutdown (i.e. BIO_CLOSE) flag.



=head1 SEE ALSO



L<bio>, L<BIO_meth_new>



=head1 HISTORY



The functions described here were added in OpenSSL version 1.1.0.



=cut

doc/crypto/BIO_meth_new.pod

0 → 100644
+117 −0
Original line number Diff line number Diff line 
=pod



=head1 NAME



BIO_meth_new, BIO_meth_free, BIO_meth_get_write, BIO_meth_set_write,

BIO_meth_get_read, BIO_meth_set_read, BIO_meth_get_puts, BIO_meth_set_puts,

BIO_meth_get_gets, BIO_meth_set_gets, BIO_meth_get_ctrl, BIO_meth_set_ctrl,

BIO_meth_get_create, BIO_meth_set_create, BIO_meth_get_destroy,

BIO_meth_set_destroy, BIO_meth_get_callback_ctrl,

BIO_meth_set_callback_ctrl  - Routines to build up BIO methods



=head1 SYNOPSIS



 #include <openssl/bio.h>



 BIO_METHOD *BIO_meth_new(int type, const char *name);

 void BIO_meth_free(BIO_METHOD *biom);

 int (*BIO_meth_get_write(BIO_METHOD *biom)) (BIO *, const char *, int);

 int BIO_meth_set_write(BIO_METHOD *biom,

                        int (*write) (BIO *, const char *, int));

 int (*BIO_meth_get_read(BIO_METHOD *biom)) (BIO *, char *, int);

 int BIO_meth_set_read(BIO_METHOD *biom,

                       int (*read) (BIO *, char *, int));

 int (*BIO_meth_get_puts(BIO_METHOD *biom)) (BIO *, const char *);

 int BIO_meth_set_puts(BIO_METHOD *biom,

                       int (*puts) (BIO *, const char *));

 int (*BIO_meth_get_gets(BIO_METHOD *biom)) (BIO *, char *, int);

 int BIO_meth_set_gets(BIO_METHOD *biom,

                       int (*gets) (BIO *, char *, int));

 long (*BIO_meth_get_ctrl(BIO_METHOD *biom)) (BIO *, int, long, void *);

 int BIO_meth_set_ctrl(BIO_METHOD *biom,

                       long (*ctrl) (BIO *, int, long, void *));

 int (*BIO_meth_get_create(BIO_METHOD *bion)) (BIO *);

 int BIO_meth_set_create(BIO_METHOD *biom, int (*create) (BIO *));

 int (*BIO_meth_get_destroy(BIO_METHOD *biom)) (BIO *);

 int BIO_meth_set_destroy(BIO_METHOD *biom, int (*destroy) (BIO *));

 long (*BIO_meth_get_callback_ctrl(BIO_METHOD *biom))

                                  (BIO *, int, bio_info_cb *);

 int BIO_meth_set_callback_ctrl(BIO_METHOD *biom,

                                long (*callback_ctrl) (BIO *, int,

                                                      bio_info_cb *));



=head1 DESCRIPTION



The B<BIO_METHOD> type is a structure used for the implementation of new BIO

types. It provides a set of of functions used by OpenSSL for the implementation

of the various BIO capabilities. See the L<bio> page for more information.



BIO_meth_new() creates a new B<BIO_METHOD> structure. It should be given a

unique integer B<type> and a string that represents its B<name>. The set of

standard OpenSSL provided BIO types is provided in B<bio.h>. Some examples

include B<BIO_TYPE_BUFFER> and B<BIO_TYPE_CIPHER>. Filter BIOs should have a

type which have the "filter" bit set (B<BIO_TYPE_FILTER>). Source/sink BIOs

should have the "source/sink" bit set (B<BIO_TYPE_SOURCE_SINK>). File descriptor

based BIOs (e.g. socket, fd, connect, accept etc) should additionally have the

"descriptor" bit set (B<BIO_TYPE_DESCRIPTOR>). See the L<BIO_find_type> page for

more information.



BIO_meth_free() destroys a B<BIO_METHOD> structure and frees up any memory

associated with it.



BIO_meth_get_write() and BIO_meth_set_write() get and set the function used for

writing arbitrary length data to the BIO respectively. This function will be

called in response to the application calling BIO_write(). The parameters for

the function have the same meaning as for BIO_write().



BIO_meth_get_read() and BIO_meth_set_read() get and set the function used for

reading arbitrary length data from the BIO respectively. This function will be

called in response to the application calling BIO_read(). The parameters for the

function have the same meaning as for BIO_read().



BIO_meth_get_puts() and BIO_meth_set_puts() get and set the function used for

writing a NULL terminated string to the BIO respectively. This function will be

called in response to the application calling BIO_puts(). The parameters for

the function have the same meaning as for BIO_puts().



BIO_meth_get_gets() and BIO_meth_set_gets() get and set the function typically

used for reading a line of data from the BIO respectively (see the L<BIO_gets>

page for more information). This function will be called in response to the

application calling BIO_gets(). The parameters for the function have the same

meaning as for BIO_gets().



BIO_meth_get_ctrl() and BIO_meth_set_ctrl() get and set the function used for

processing ctrl messages in the BIO respectively. See the L<BIO_ctrl> page for

more information. This function will be called in response to the application

calling BIO_ctrl(). The parameters for the function have the same meaning as for

BIO_ctrl().



BIO_meth_get_create() and BIO_meth_set_create() get and set the function used

for creating a new instance of the BIO respectively. This function will be

called in response to the application calling BIO_new() or BIO_set() and passing

in a pointer to the current BIO_METHOD. The BIO_new() function will allocate the

memory for the new BIO, and a pointer to this newly allocated structure will

be passed as a parameter to the function.



BIO_meth_get_destroy() and BIO_meth_set_destroy() get and set the function used

for destroying an instance of a BIO respectively. This function will be

called in response to the application calling BIO_free(). A pointer to the BIO

to be destroyed is passed as a parameter. The destroy function should be used

for BIO specific clean up. The memory for the BIO itself should not be freed by

this function.



BIO_meth_get_callback_ctrl() and BIO_meth_set_callback_ctrl() get and set the

function used for processing callback ctrl messages in the BIO respectively. See

the L<BIO_callback_ctrl> page for more information. This function will be called

in response to the application calling BIO_callback_ctrl(). The parameters for

the function have the same meaning as for BIO_callback_ctrl().



=head1 SEE ALSO



L<bio>, L<BIO_find_type>, L<BIO_ctrl>, L<BIO_read>, L<BIO_new>



=head1 HISTORY



The functions described here were added in OpenSSL version 1.1.0.



=cut

doc/crypto/BIO_push.pod

+15 −4
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ 


=head1 NAME



BIO_push, BIO_pop - add and remove BIOs from a chain.

BIO_push, BIO_pop, BIO_set_next - add and remove BIOs from a chain.



=head1 SYNOPSIS
@@ -10,6 +10,7 @@ BIO_push, BIO_pop - add and remove BIOs from a chain. 


 BIO *BIO_push(BIO *b,BIO *append);

 BIO *BIO_pop(BIO *b);

 void BIO_set_next(BIO *b, BIO *next);



=head1 DESCRIPTION
@@ -21,6 +22,10 @@ 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_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

or it may be completely different.



=head1 NOTES



The names of these functions are perhaps a little misleading. BIO_push()
@@ -66,4 +71,10 @@ BIO. 


=head1 SEE ALSO



TBA
 
L<bio>



=head1 HISTORY



The BIO_set_next() function was added in OpenSSL version 1.1.0.



=cut

doc/crypto/BIO_should_retry.pod

+16 −4
Original line number Diff line number Diff line
@@ -4,7 +4,8 @@ 


BIO_should_retry, BIO_should_read, BIO_should_write,

BIO_should_io_special, BIO_retry_type, BIO_should_retry,

BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions

BIO_get_retry_BIO, BIO_get_retry_reason, BIO_set_retry_reason - BIO retry

functions



=head1 SYNOPSIS
@@ -24,6 +25,7 @@ BIO_get_retry_BIO, BIO_get_retry_reason - BIO retry functions 


 BIO *BIO_get_retry_BIO(BIO *bio, int *reason);

 int BIO_get_retry_reason(BIO *bio);

 void BIO_set_retry_reason(BIO *bio, int reason);



=head1 DESCRIPTION
@@ -59,6 +61,9 @@ the type of BIO that resulted in this condition. 
BIO_get_retry_reason() returns the reason for a special condition if

passed the relevant BIO, for example as returned by BIO_get_retry_BIO().



BIO_set_retry_reason() sets the retry reason for a special condition for a given

BIO. This would usually only be called by BIO implementations.



=head1 NOTES



If BIO_should_retry() returns false then the precise "error condition"
@@ -111,4 +116,11 @@ the entire structure can be read or written. 


=head1 SEE ALSO



TBA
 
L<bio>



=head1 HISTORY



The BIO_get_retry_reason() and BIO_set_retry_reason() functions were added in

OpenSSL version 1.1.0.



=cut