- * +----------------+---------------------------+
- * | written data | free space |
- * +----------------+---------------------------+
- * ^ ^ ^
- * buffer=bstop bptr bufend
+ * +--------+--------------+--------------------+
+ * | unused | written data | free space |
+ * +--------+--------------+--------------------+
+ * ^ ^ ^ ^
+ * buffer bstop bptr bufend
+ *
+ * Dirty tricks:
+ *
+ * - You can mix reads and writes on the same stream, but you must
+ * call bflush() in between and remember that the file position
+ * points after the flushed buffer which is not necessarily the same
+ * as after the data you've read.
+ * - The spout/refill hooks can change not only bptr and bstop, but also
+ * the location of the buffer; fb-mem.c takes advantage of it.