From: Pavel Charvat <pchar@ucw.cz>
Date: Thu, 6 Nov 2008 10:03:41 +0000 (+0100)
Subject: Doc: Described ff-binary.
X-Git-Tag: holmes-import~195
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=6cbd32307057f98fc793eaf9dc97c99c62a85a43;p=libucw.git

Doc: Described ff-binary.
---

diff --git a/ucw/doc/fastbuf.txt b/ucw/doc/fastbuf.txt
index 894d0780..d94fffe9 100644
--- a/ucw/doc/fastbuf.txt
+++ b/ucw/doc/fastbuf.txt
@@ -60,4 +60,4 @@ Invalid codes are replaced by `UNI_REPLACEMENT` when reading.
 ucw/ff-binary.h
 ---------------
 
-Reading and writing of binary values.
+!!ucw/ff-binary.h
diff --git a/ucw/ff-binary.h b/ucw/ff-binary.h
index edba770c..0e9144d5 100644
--- a/ucw/ff-binary.h
+++ b/ucw/ff-binary.h
@@ -20,6 +20,32 @@
 #define FF_ENDIAN le
 #endif
 
+/***
+ *
+ * We define several functions to read or write binary integer values.
+ *
+ * The name patterns for such routines are:
+ *
+ * - `TYPE bget \#\# NAME \#\# ENDIAN(struct fastbuf *f);`
+ * - `void bput \#\# NAME \#\# ENDIAN(struct fastbuf *f, TYPE value);`
+ *
+ * where `NAME` together with `TYPE` can be:
+ *
+ * - `w` for 16-bit unsigned integers stored in sequences of 2 bytes, the `TYPE` is int
+ * - `l` for 32-bit unsigned integers stored in sequences of 4 bytes, the `TYPE` is uns
+ * - `5` for 40-bit unsigned integers stored in sequences of 5 bytes, the `TYPE` is u64
+ * - `q` for 64-bit unsigned integers stored in sequences of 8 bytes, the `TYPE` is u64
+ *
+ * and supported `ENDIAN` suffixes are:
+ *
+ * - empty for the default order of bytes (defined by CPU)
+ * - `_le` for little-endian
+ * - `_be` for big-endian
+ *
+ * If we fail to read enough bytes because the EOF, the reading function returns `(TYPE)-1`.
+ *
+ ***/
+
 #define GET_FUNC(type, name, bits, endian)			\
   type bget##name##_##endian##_slow(struct fastbuf *f);		\
   static inline type bget##name##_##endian(struct fastbuf *f)	\