From: Dr. Stephen Henson Date: Thu, 14 Sep 2000 18:55:39 +0000 (+0000) Subject: BIO_s_bio() manual page detailing BIO pair. X-Git-Tag: OpenSSL-engine-0_9_6-beta2~9^2~15 X-Git-Url: https://git.openssl.org/?p=openssl.git;a=commitdiff_plain;h=18f22594994da8b2a2a11786b2a106ca8d94f1ed BIO_s_bio() manual page detailing BIO pair. This combines several manual pages provided by Lutz Jaenicke , various comments by Bodo to the lists and a bit of source examination by me. --- diff --git a/doc/crypto/BIO_s_bio.pod b/doc/crypto/BIO_s_bio.pod new file mode 100644 index 0000000000..5867bc5a8f --- /dev/null +++ b/doc/crypto/BIO_s_bio.pod @@ -0,0 +1,114 @@ +=pod + +=head1 NAME + +BIO_s_bio - BIO pair + +=head1 SYNOPSIS + + #include + + BIO_METHOD *BIO_s_bio(void); + + #define BIO_make_bio_pair(b1,b2) (int)BIO_ctrl(b1,BIO_C_MAKE_BIO_PAIR,0,b2) + #define BIO_destroy_bio_pair(b) (int)BIO_ctrl(b,BIO_C_DESTROY_BIO_PAIR,0,NULL) + + #define BIO_set_write_buf_size(b,size) (int)BIO_ctrl(b,BIO_C_SET_WRITE_BUF_SIZE,size,NULL) + #define BIO_get_write_buf_size(b,size) (size_t)BIO_ctrl(b,BIO_C_GET_WRITE_BUF_SIZE,size,NULL) + + int BIO_new_bio_pair(BIO **bio1, size_t writebuf1, BIO **bio2, size_t writebuf2); + + #define BIO_get_write_guarantee(b) (int)BIO_ctrl(b,BIO_C_GET_WRITE_GUARANTEE,0,NULL) + size_t BIO_ctrl_get_write_guarantee(BIO *b); + + #define BIO_get_read_request(b) (int)BIO_ctrl(b,BIO_C_GET_READ_REQUEST,0,NULL) + size_t BIO_ctrl_get_read_request(BIO *b); + + int BIO_ctrl_reset_read_request(BIO *b); + +=head1 DESCRIPTION + +BIO_s_bio() returns the method for a BIO pair. A BIO pair is a pair of source/sink +BIOs where data written to either half of the pair is buffered and can be read from +the other half. + +Since BIO chains typically end in a source/sink BIO it is possible to make this +one half of a BIO pair and have all the data processed by the chain under application +control. + +One typical use of BIO pairs is to place SSL I/O under application control, this +can be used when the application wishes to use a non standard trasport for +SSL or the normal socket routines are inappropriate. + +Calls to BIO_read() will read data from the buffer or request a retry if no +data is available. + +Calls to BIO_write() will place data in the buffer or request a retry if the +buffer is full. + +The standard calls BIO_ctrl_pending() and BIO_ctrl_wpending() can be used to +determine the amount of pending data in the read or write buffer. + +BIO_reset() clears any data in the write buffer. + +BIO_make_bio_pair() joins two separate BIOs into a connected pair. + +BIO_destroy_pair() destroys the association between two connected BIOs. Freeing +up both halves of the pair will automatically destroy the association. + +BIO_set_write_buf_size() sets the write buffer size of BIO B to B. +If the size is not initialised a default value is used. This is currently +17K, sufficient for a maximum size TLS record. + +BIO_get_write_buf_size() returns the size of the write buffer. + +BIO_new_bio_pair() combines the calls to BIO_new(), BIO_make_bio_pair() and +BIO_set_write_buf_size() to create a connected pair of BIOs B, B +with write buffer sizes B and B. If either size is +zero then the default size is used. + +BIO_get_write_guarantee() and BIO_ctrl_get_write_guarentee() return the maximum +length of data that can be currently written to the BIO. Writes larger than this +value will return a value from BIO_write() less than the amount requested or if the +buffer is full request a retry. BIO_ctrl_get_write_guarantee() is a function +whereas BIO_get_write_guarantee() is a macro. + +BIO_get_read_request() and BIO_ctrl_get_read_request() return the amount of data +requested (or the buffer size if it is less) if the last read failed due to an +empty buffer. This can be used to determine how much data should be written to the +other half of the pair so the next read will succeed: this is most useful in SSL +applications where the amount of data read is usually meaningful rather than just +a buffer size. After a successful read this call will return zero. + +BIO_ctrl_reset_read_request() can also be used to reset the value returned by +BIO_get_read_request() to zero. + +=head1 NOTES + +Both halves of a BIO pair should be freed. That is even if one half is implicity +freed due to a BIO_free_all() or SSL_free() call the other half needs to be freed. + +When used in bidirectional applications (such as SSL) care should be taken to +flush any data in the write buffer. This can be done by calling BIO_pending() +on the other half of the pair and, if any data is pending, reading it and sending +it to the underlying transport. This must be done before any normal processing +(such as calling select() ) due to a request and BIO_should_read() being true. + +To see why this is important consider a case where a request is sent using +BIO_write() and a response read with BIO_read(), this can occur during an +SSL handshake for example. BIO_write() will succeed and place data in the write +buffer. BIO_read() will initially fail and BIO_should_read() will be true. If +the application then waits for data to be available on the underlying transport +before flusing the write buffer it will never succeed because the request was +never sent! + +=head1 EXAMPLE + +TBA + +=head1 SEE ALSO + +L, L, L, +L, L + +=cut