document global structure better

README.md

@@ -71,49 +71,45 @@ CHM than with BDZ, eliminating the benefit of preserved ordering.
 Full file structure
 -------------------
 
-The file structure stars with magic and version number, followed by a list of
-User, Group records and their indices. All indices are number of bytes,
-relative to the beginning of the file.
+The turbonss header looks like this:
+
 
 ```
-const File = struct {
-    magic: [4]u8,
-    version: u4,
-    padding: u4,
-    num_shells: u6,
-    padding: u2,
-    num_users: u32,
-    num_groups: u32,
-    offset_cmph_gid2group: u26,
-    offset_cmph_uid2user: u26,
-    offset_cmph_groupname2group: u26,
-    offset_cmph_username2user: u26,
-    offset_sorted_groups: u26,
-    offset_sorted_users: u26,
-    offset_groupmembers: u26,
-    offset_additional_gids: u26,
-}
+OFFSET     TYPE     NAME                          DESCRIPTION
+   0      [4]u8     magic                         always 0xf09fa4b7
+   4         u8     version                       now `0`
+   5         u2     padding
+             u6     num_shells                    see "SHELLS" section.
+   6        u32     num_users                     number of passwd entries
+  10        u32     num_groups                    number of group entries
+  14        u32     offset_cmph_gid2group
+  18        u32     offset_cmph_uid2user
+  22        u32     offset_cmph_groupname2group
+  26        u32     offset_cmph_username2user
+  30        u32     offset_sorted_groups
+  34        u32     offset_sorted_users
+  38        u32     offset_groupmembers
+  42        u32     offset_additional_gids
 ```
 
-`magic` is 0xf09fa4b7, and `version` must be `0`. Offsets are indices to
-further sections of the file, with zero being the first block (the magic
-number). As all blobs are 64-byte aligned, the offsets are pointing to the
-beginning of the 64-byte "block" (thus u26). All numbers are little-endian.
-
-As of writing the file header is 40 bytes.
+`magic` is 0xf09fa4b7, and `version` must be `0`. All integers are big-endian.
+Offsets are indices to further sections of the file, with zero being the first
+block (the magic number). As all blobs are 64-byte aligned, the offsets are
+always pointing to the beginning of an 64-byte "block". Therefore, all
+`offset_*` values could be `u26`. As `u32` is easier to visualize with xxd, and
+the File block fits to 64 bytes anyway, we are keeping them as u32 now.
 
 Primitive types:
 
 ```
 const Group = struct {
     gid: u32,
-    // index to a separate structure with a list of members
-    members_offset: u29,
-    padding: u3,
-    groupname_len: u8,
-    // a variable-sized array that will be stored immediately after this
-    // struct.
-    stringdata []u8;
+    // index to a separate structure with a list of members. The memberlist is
+    // always 2^5-byte aligned, this is an index there.
+    members_offset: u27,
+    groupname_len: u5,
+    // a groupname_len-sized string
+    groupname []u8;
 }
 
 const User = struct {
@@ -125,7 +121,8 @@ const User = struct {
     shell_here: u1,
     shell_len_or_place: u6,
     home_len: u6,
-    username_len: u6,
+    username_pos: u1,
+    username_len: u5,
     gecos_len: u8,
     // a variable-sized array that will be stored immediately after this
     // struct.