commit 77d4b9de4d6b29c35b13413e47c4e8e4693226e3
parent 8570bc7e66b8ea92daa1c57ecdf2ecea29e7fcda
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 13 Jun 2022 16:31:42 +0200
Improve the sbuf man page
Add the description of the sbuf fileformat
Diffstat:
1 file changed, 20 insertions(+), 0 deletions(-)
diff --git a/doc/sbuf.5.scd b/doc/sbuf.5.scd
@@ -19,6 +19,22 @@ sbuf(5)
sbuf - Star-Buffer file format
+# DESCRIPTION
+
+*sbuf* is a binary file format for storing data in a 1-dimensional array.
+
+A *sbuf* file begins with a header of four 64-bits integers. The first integer
+is a power of two (usually 4096) that defines the size of the memory page in
+bytes (_pagesize_) on wich the array is aligned. By aligning the array on
+_pagesize_, and depending on system requirements, memory mapping can be used to
+automatically load/unload the array items on demand (see *mmap*(2)). The second
+integer is the _size_ of the array. Finally, the 2 remaining integers store the
+memory size and the memory alignment of each array element.
+
+Fill bytes follow the file header to align the array to _pagesize_. The array
+elements are then listed. Fill bytes are finally added to ensure that the
+overall file size is a multiple of _pagesize_.
+
# BINARY FILE
Data are encoded with respect to the little endian bytes ordering, i.e. least
@@ -44,3 +60,7 @@ significant bytes are stored first.
<padding> ::= [ BYTE ... ] # Ensure alignement
```
+
+# SEE ALSO
+
+*mmap*(2)
