formatted operations.
Please keep in mind that fastbufs do not allow arbitrary mixing of reads and
-writes on the same stream. If you need to mix them, you have to call bflush()
-inbetween and remember that the file position reported by btell() points after
+writes on the same stream. If you need to mix them, you have to call @bflush()
+inbetween and remember that the file position reported by @btell() points after
the flushed buffer, which is not necessarily the same as after the data you've
really read.
+Fastbufs can also participate in the libucw resource management system.
+You can tie a fastbuf to a resource in the current resource pool by @fb_tie().
+When the pool gets cleaned up, the fastbuf is automatically closed. If you call
+@bclose() explicitly, the resource is removed, too.
+
.Back-ends:
-- xref:fbparam[Files (parametrized)]
-- xref:fbfile[Regular files]
-- xref:fbtemp[Temporary files]
-- xref:fblim[File fragments]
-- xref:fbmem[In-memory streams]
-- xref:fbbuf[Buffers]
-- xref:fbgrow[Growing buffers]
-- xref:fbpool[Memory pools]
-- xref:fbatomic[Atomic files]
+- <<fbparam,Files (parametrized)>>
+- <<fbfile,Regular files>>
+- <<fbtemp,Temporary files>>
+- <<fblim,File fragments>>
+- <<fbmem,In-memory streams>>
+- <<fbbuf,Buffers>>
+- <<fbgrow,Growing buffers>>
+- <<fbpool,Memory pools>>
+- <<fbatomic,Atomic files>>
.Front-ends:
-- xref:ffbasic[Basic functions]
+- <<ffbasic,Basic functions>>
.Other reading:
-- xref:internal[Internal structure]
-- xref:bconfig[Configuring streams]
+- <<internal,Internal structure>>
+- <<bconfig,Configuring streams>>
+- <<fbexc,Exceptions>>
ucw/fastbuf.h
-------------
Reading and writing of unicode characters.
-Invalid codes are replaced by +UNI_REPLACEMENT+ when reading.
+Invalid codes are replaced by `UNI_REPLACEMENT` when reading.
!!ucw/ff-unicode.h
ucw/ff-binary.h
---------------
-Reading and writing of binary values.
+!!ucw/ff-binary.h
+
+Exceptions [[fbexc]]
+--------------------
+
+All standard back-ends and front-ends raise exceptions on errors. All such
+exceptions live in the `ucw.fb` subtree. The following exceptions are defined:
+
+`ucw.fb.eof`:: Unexpected end of file (e.g., when the @FB_DIE_ON_EOF flag is set)
+`ucw.fb.mmap`:: Memory mapping failed (e.g., the `mmap` syscall has failed)
+`ucw.fb.open`:: Opening failed (file does not exist and similar problems)
+`ucw.fb.read`:: Read error (e.g., the `read` syscall has failed or the stream is write-only)
+`ucw.fb.seek`:: Seek error (e.g., file not seekable, or a seek behind EOF)
+`ucw.fb.tmp`:: Creation of temporary file failed
+`ucw.fb.toolong`:: Object (typically a line) is too long
+`ucw.fb.write`:: Write error (e.g., the `write` syscall has failed or the stream is read-only)