[readme] add file structure

README.md

@@ -91,8 +91,8 @@ The following operations need to be fast, in order of importance:
 
 1. lookup gid -> group (this is on hot path in id).
 2. lookup uid -> user.
-3. lookup username -> user.
-4. lookup groupname -> group.
+3. lookup groupname -> group.
+4. lookup username -> user.
 5. (optional) iterate users using a defined order (`getent passwd`).
 6. (optional) iterate groups using a defined order (`getent group`).
 
@@ -107,5 +107,36 @@ BDZ: tried b=3, b=7 (default), and b=10.
 CHM retains order, however, 1M keys weigh 8MB. 10k keys are ~20x larger with
 CHM than with BDZ, eliminating the benefit of preserved ordering.
 
+Full file structure
+-------------------
+
+The file structure stars with the metadata field. All indexes are number of
+bytes, relative to the beginning of the file.
+
+```
+const Offsets = struct {
+   magic: [4]u32,
+   version: u32,
+
+   num_users, size_num_users: u32,
+   num_groups, size_num_groups: u32,
+   cmph_gid2group: u32,
+   size_cmph_gid2group: u32,
+   cmph_uid2user, size_cmph_uid2user: u32,
+   cmph_groupname2group, size_cmph_groupname2group: u32,
+   cmph_username2user, size_cmph_username2user: u32,
+   structs_group, size_structs_group: u32,
+   structs_user, size_structs_user: u32,
+   fsst_usernames_homes, size_fsst_usernames_homes: u32,
+   fsst_groupnames, size_fsst_usernames_homes: u32,
+   fsst_shells, size_fsst_shells: u32,
+}
+```
+
+`magic` must be 0xf09fa4b7, and `version` must be `0x00`. The remaining fields
+are indexes to further sections of the file with their sizes in bytes. All
+numbers are little-endian. Each field may be aligned to 64B (L1D cache size) or
+4KB (standard page size), to be decided.
+
 [git-subtrac]: https://github.com/apenwarr/git-subtrac/
 [cmph]: http://cmph.sourceforge.net/