sbuf.5 (2548B)
1 .\" Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com) 2 .\" 3 .\" This program is free software: you can redistribute it and/or modify 4 .\" it under the terms of the GNU General Public License as published by 5 .\" the Free Software Foundation, either version 3 of the License, or 6 .\" (at your option) any later version. 7 .\" 8 .\" This program is distributed in the hope that it will be useful, 9 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of 10 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11 .\" GNU General Public License for more details. 12 .\" 13 .\" You should have received a copy of the GNU General Public License 14 .\" along with this program. If not, see <http://www.gnu.org/licenses/>. 15 .Dd October 27, 2023 16 .Dt SBUF 5 17 .Os 18 .Sh NAME 19 .Nm sbuf 20 .Nd Star-Buffer file format 21 .Sh DESCRIPTION 22 .Nm 23 is a binary file format for storing data in a 1-dimensional array. 24 .Pp 25 A 26 .Nm 27 file begins with a header of four 64-bits integers. 28 The first integer is a power of two 29 .Pq usually 4096 30 that defines the size of the memory page in bytes 31 .Pq Va pagesize 32 on wich the array is aligned. 33 By aligning the array on 34 .Va pagesize , 35 and depending on system requirements, memory mapping can be used to 36 automatically load/unload the array items on demand 37 .Pq see Xr mmap 2 . 38 The second integer is the 39 .Va size 40 of the array. 41 Finally, the 2 remaining integers store the memory size and the memory 42 alignment of each array element. 43 .Pp 44 Fill bytes follow the file header to align the array to 45 .Va pagesize . 46 The array elements are then listed. 47 Fill bytes are finally added to ensure that the overall file size is a multiple 48 of 49 .Va pagesize . 50 .Pp 51 Data are encoded with respect to the little endian bytes ordering, i.e. least 52 significant bytes are stored first. 53 .Pp 54 The file format is as follows: 55 .Bl -column (pagesize) (::=) () 56 .It Ao Va sbuf Ac Ta ::= Ta 57 .Aq Va pagesize 58 .Aq Va size 59 .Aq Va szitem 60 .Aq Va alitem 61 .It Ta Ta Aq Va padding 62 .It Ta Ta Aq Va list 63 .It Ta Ta Aq Va padding 64 .It \ Ta Ta 65 .It Ao Va pagesize Ac Ta ::= Ta Vt uint64_t 66 .It Ao Va size Ac Ta ::= Ta Vt uint64_t 67 # Number of items stored 68 .It Ao Va szitem Ac Ta ::= Ta Vt uint64_t 69 # Size of an item in bytes 70 .It Ao Va alitem Ac Ta ::= Ta Vt uint64_t 71 # Alignement of an item (<= pagesize) 72 .It \ Ta Ta 73 .It Ao Va list Ac Ta ::= Ta Ao Va element Ac Va ... 74 .It Ao Va element Ac Ta ::= Ta Ao Va item Ac Ao Va padding Ac 75 .It Ao Va item Ac Ta ::= Ta Vt char ... 76 .It \ Ta Ta 77 .It Ao Va padding Ac Ta ::= Ta Op Vt int8_t ... 78 # Ensure alignment on 79 .Va pagesize 80 .El 81 .Sh SEE ALSO 82 .Xr mmap 2