doc/fastbuf.txt

   1 Fastbufs
   2 ========
   3
   4 A *fastbuf* is a stream (or file) abstraction optimized for both speed
   5 and flexibility.
   6
   7 Fastbufs can represent many different kinds of objects: regular files, network
   8 sockets, file descriptors in general, or various memory buffers. These objects
   9 are handled by different fastbuf *back-ends.*
  10
  11 Once you have a fastbuf, you can access it by fuctions similar to those of
  12 `stdio.h`, or you can use a variety of fastbuf *front-ends* providing various
  13 formatted operations.
  14
  15 Please keep in mind that fastbufs do not allow arbitrary mixing of reads and
  16 writes on the same stream. If you need to mix them, you have to call @bflush()
  17 inbetween and remember that the file position reported by @btell() points after
  18 the flushed buffer, which is not necessarily the same as after the data you've
  19 really read.
  20
  21 Fastbufs can also participate in the libucw resource management system.
  22 You can tie a fastbuf to a resource in the current resource pool by @fb_tie().
  23 When the pool gets cleaned up, the fastbuf is automatically closed. If you call
  24 @bclose() explicitly, the resource is removed, too.
  25
  26 .Back-ends:
  27 - <<fbparam,Files (parametrized)>>
  28 - <<fbfile,Regular files>>
  29 - <<fbtemp,Temporary files>>
  30 - <<fblim,File fragments>>
  31 - <<fbmem,In-memory streams>>
  32 - <<fbbuf,Buffers>>
  33 - <<fbgrow,Growing buffers>>
  34 - <<fbpool,Memory pools>>
  35 - <<fbatomic,Atomic files>>
  36
  37 .Front-ends:
  38 - <<ffbasic,Basic functions>>
  39
  40 .Other reading:
  41 - <<internal,Internal structure>>
  42 - <<bconfig,Configuring streams>>
  43 - <<fbexc,Exceptions>>
  44
  45 ucw/fastbuf.h
  46 -------------
  47
  48 !!ucw/fastbuf.h
  49
  50 ucw/fb-socket.h
  51 ---------------
  52
  53 Fastbufs on network sockets with timeouts.
  54
  55 !!ucw/fb-socket.h
  56
  57 ucw/ff-unicode.h
  58 ----------------
  59
  60 Reading and writing of unicode characters.
  61
  62 Invalid codes are replaced by `UNI_REPLACEMENT` when reading.
  63
  64 !!ucw/ff-unicode.h
  65
  66 ucw/ff-binary.h
  67 ---------------
  68
  69 !!ucw/ff-binary.h
  70
  71 Exceptions [[fbexc]]
  72 --------------------
  73
  74 All standard back-ends and front-ends raise exceptions on errors. All such
  75 exceptions live in the `ucw.fb` subtree. The following exceptions are defined:
  76
  77 `ucw.fb.eof`:: Unexpected end of file (e.g., when the @FB_DIE_ON_EOF flag is set)
  78 `ucw.fb.mmap`:: Memory mapping failed (e.g., the `mmap` syscall has failed)
  79 `ucw.fb.open`:: Opening failed (file does not exist and similar problems)
  80 `ucw.fb.read`:: Read error (e.g., the `read` syscall has failed or the stream is write-only)
  81 `ucw.fb.seek`:: Seek error (e.g., file not seekable, or a seek behind EOF)
  82 `ucw.fb.tmp`:: Creation of temporary file failed
  83 `ucw.fb.write`:: Write error (e.g., the `write` syscall has failed or the stream is read-only)