From 3b2cbbcb9ae6093510b00c459e73104095a29ab9 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Mon, 18 Sep 2000 23:05:33 +0000 Subject: [PATCH] Clarify the BIO_seek() mess and related issues. Buffering BIO docs. --- doc/crypto/BIO_ctrl.pod | 28 ++++++++++----- doc/crypto/BIO_f_buffer.pod | 69 +++++++++++++++++++++++++++++++++++++ doc/crypto/BIO_s_file.pod | 11 ++++-- 3 files changed, 98 insertions(+), 10 deletions(-) create mode 100644 doc/crypto/BIO_f_buffer.pod diff --git a/doc/crypto/BIO_ctrl.pod b/doc/crypto/BIO_ctrl.pod index acc46db8ce..722e8b8f46 100644 --- a/doc/crypto/BIO_ctrl.pod +++ b/doc/crypto/BIO_ctrl.pod @@ -47,8 +47,8 @@ BIO_reset() typically resets a BIO to some initial state, in the case of file related BIOs for example it rewinds the file pointer to the start of the file. -BIO_seek() resets a file related BIO's file position pointer to B -bytes from start of file. +BIO_seek() resets a file related BIO's (that is file descriptor and +FILE BIOs) file position pointer to B bytes from start of file. BIO_tell() returns the current file position of a file related BIO. @@ -73,10 +73,12 @@ macros which call BIO_ctrl(). =head1 RETURN VALUES -BIO_reset() returns 1 for success and 0 for failure. +BIO_reset() normally returns 1 for success and 0 or -1 for failure. File +BIOs are an exception, they return 0 for success and -1 for failure. BIO_seek() and BIO_tell() both return the current file position on success -and -1 for failure. +and -1 for failure, except file BIOs which for BIO_seek() always return 0 +for success and -1 for failure. BIO_flush() returns 1 for success and 0 or -1 for failure. @@ -102,14 +104,24 @@ case of a file BIO some data may be available in the FILE structures internal buffers but it is not possible to determine this in a portably way. For other types of BIO they may not be supported. -Filter BIOs if the do not internally handle a particular BIO_ctrl() +Filter BIOs if they do not internally handle a particular BIO_ctrl() operation usually pass the operation to the next BIO in the chain. This often means there is no need to locate the required BIO for a particular operation, it can be called on a chain and it will -be automatically passed to the relevant BIO. +be automatically passed to the relevant BIO. However this can cause +unexpected results: for example no current filter BIOs implement +BIO_seek(), but this may still succeed if the chain ends in a FILE +or file descriptor BIO. -Source/sink BIOs will return an error if the do not recognize the -BIO_ctrl() operation. +Source/sink BIOs return an 0 if they do not recognize the BIO_ctrl() +operation. + +=head1 BUGS + +Some of the return values are ambiguous and care should be taken. In +particular a return value of 0 can be returned if an operation is not +supported, if an error occurred, if EOF has not been reached and in +the case of BIO_seek() on a file BIO for a successful operation. =head1 SEE ALSO diff --git a/doc/crypto/BIO_f_buffer.pod b/doc/crypto/BIO_f_buffer.pod new file mode 100644 index 0000000000..c9093c6a57 --- /dev/null +++ b/doc/crypto/BIO_f_buffer.pod @@ -0,0 +1,69 @@ +=pod + +=head1 NAME + +BIO_f_buffer - buffering BIO + +=head1 SYNOPSIS + + #include + + BIO_METHOD * BIO_f_buffer(void); + + #define BIO_get_buffer_num_lines(b) BIO_ctrl(b,BIO_C_GET_BUFF_NUM_LINES,0,NULL) + #define BIO_set_read_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,0) + #define BIO_set_write_buffer_size(b,size) BIO_int_ctrl(b,BIO_C_SET_BUFF_SIZE,size,1) + #define BIO_set_buffer_size(b,size) BIO_ctrl(b,BIO_C_SET_BUFF_SIZE,size,NULL) + #define BIO_set_buffer_read_data(b,buf,num) BIO_ctrl(b,BIO_C_SET_BUFF_READ_DATA,num,buf) + +=head1 DESCRIPTION + +BIO_f_buffer() returns the buffering BIO method. + +Data written to a buffering BIO is buffered and periodically written +to the next BIO in the chain. Data read from a buffering BIO comes from +an internal buffer which is filled from the next BIO in the chain. +Both BIO_gets() and BIO_puts() are supported. + +Calling BIO_reset() on a buffering BIO clears any buffered data. + +BIO_get_buffer_num_lines() returns the number of lines currently buffered. + +BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() +set the read, write or both read and write buffer sizes to B. The initial +buffer size is DEFAULT_BUFFER_SIZE, currently 1024. Any attempt to reduce the +buffer size below DEFAULT_BUFFER_SIZE is ignored. Any buffered data is cleared +when the buffer is resized. + +BIO_set_buffer_read_data() clears the read buffer and fills it with B +bytes of B. If B is larger than the current buffer size the buffer +is expanded. + +=head1 NOTES + +Buffering BIOs implement BIO_gets() by using BIO_read() operations on the +next BIO in the chain. By prepending a buffering BIO to a chain it is therefore +possible to provide BIO_gets() functionality if the following BIOs do not +support it (for example SSL BIOs). + +Data is only written to the next BIO in the chain when the write buffer fills +or when BIO_flush() is called. It is therefore important to call BIO_flush() +whenever any pending data should be written such as when removing a buffering +BIO using BIO_pop(). BIO_flush() may need to be retried if the ultimate +source/sink BIO is non blocking. + +=head1 RETURN VALUES + +BIO_f_buffer() returns the buffering BIO method. + +BIO_get_buffer_num_lines() returns the number of lines buffered (may be 0). + +BIO_set_read_buffer_size(), BIO_set_write_buffer_size() and BIO_set_buffer_size() +return 1 if the buffer was successfully resized or 0 for failure. + +BIO_set_buffer_read_data() returns 1 if the data was set correctly or 0 if +there was an error. + +=head1 SEE ALSO + +TBA diff --git a/doc/crypto/BIO_s_file.pod b/doc/crypto/BIO_s_file.pod index d449702bff..b2a29263f4 100644 --- a/doc/crypto/BIO_s_file.pod +++ b/doc/crypto/BIO_s_file.pod @@ -38,7 +38,7 @@ BIO_reset() attempts to change the file pointer to the start of file using fseek(stream, 0, 0). BIO_seek() sets the file pointer to position B from start of file -using lseek(stream, ofs, 0). +using fseek(stream, ofs, 0). BIO_eof() calls feof(). @@ -105,7 +105,7 @@ Alternative technique: BIO *out; out = BIO_new(BIO_s_file()); if(out == NULL) /* Error ... */ - if(!BIO_read_filename(out, "filename.txt")) /* Error ... */ + if(!BIO_write_filename(out, "filename.txt")) /* Error ... */ BIO_printf(out, "Hello World\n"); BIO_free(out); @@ -127,6 +127,13 @@ BIO_tell() returns the current file position. BIO_read_filename(), BIO_write_filename(), BIO_append_filename() and BIO_rw_filename() return 1 for success or 0 for failure. +=head1 BUGS + +BIO_reset() and BIO_seek() are implemented using fseek() on the underlying +stream. The return value for fseek() is 0 for success or -1 if an error +occurred this differs from other types of BIO which will typically return +1 for success and a non positive value if an error occurred. + =head1 SEE ALSO L, L, -- 2.34.1