Codebase list openssl / 525e228
DOC: document in more detail what a BIO_read_ex() via BIO_f_buffer() does The BIO_f_buffer() documentation tells in enough detail how it affects BIO_gets(), but not how it affects BIO_read_ex(). This change remedies that. Fixes #10859 Reviewed-by: Tim Hudson <tjh@openssl.org> (Merged from https://github.com/openssl/openssl/pull/10890) (cherry picked from commit 9a4fd80ee0ad1833879b6a55c9c4673eeb8446a3) Richard Levitte 4 years ago
1 changed file(s) with 14 addition(s) and 4 deletion(s). Raw diff Collapse all Expand all
+14
-4
doc/man3/BIO_f_buffer.pod less more
4848
4949 These functions, other than BIO_f_buffer(), are implemented as macros.
5050
51 Buffering BIOs implement BIO_gets() by using BIO_read_ex() operations on the
52 next BIO in the chain. By prepending a buffering BIO to a chain it is therefore
53 possible to provide BIO_gets() functionality if the following BIOs do not
54 support it (for example SSL BIOs).
51 Buffering BIOs implement BIO_read_ex() and BIO_gets() by using
52 BIO_read_ex() operations on the next BIO in the chain and storing the
53 result in an internal buffer, from which bytes are given back to the
54 caller as appropriate for the call; a BIO_gets() is guaranteed to give
55 the caller a whole line, and BIO_read_ex() is guaranteed to give the
56 caller the number of bytes it asks for, unless there's an error or end
57 of communication is reached in the next BIO. By prepending a
58 buffering BIO to a chain it is therefore possible to provide
59 BIO_gets() or exact size BIO_read_ex() functionality if the following
60 BIOs do not support it.
61
62 Do not add more than one BIO_f_buffer() to a BIO chain. The result of
63 doing so will force a full read of the size of the internal buffer of
64 the top BIO_f_buffer(), which is 4 KiB at a minimum.
5565
5666 Data is only written to the next BIO in the chain when the write buffer fills
5767 or when BIO_flush() is called. It is therefore important to call BIO_flush()