Region Header Layout

The 64-byte header at the start of every shared memory region

Every mapped Zinc region begins with a 64-byte header. The header is #[repr(C, align(64))] in Rust, meaning its layout is stable and exactly 64 bytes. The header occupies the start of the first page. Data begins at offset page_size, after the rest of that page’s padding.

Layout

Offset  Size    Type          Field        Description
------  ------  ------------  -----------  -----------------------------------
0       8       AtomicU64     magic        Magic number for corruption detection
8       2       u16           version      Breaking-change guard (currently 2)
10      2       u16           flags        Reserved
12      4       AtomicU32     notify_seq   Notification/futex signal counter
16      8       u64           capacity     Usable bytes after header
24      4       AtomicU32     ref_count    Open handle count
28      4       AtomicI32     owner_pid    PID of creating process
32      8       u64           created_at   Unix timestamp (nanoseconds)
40      8       u64           name_hash    FNV-1a hash of region name
48      8       AtomicU64     ring_head    Notification ring write position
56      8       AtomicU64     ring_tail    Notification ring read position

Total: 64 bytes.

Fields

magic (offset 0, 8 bytes)

Published with a release store after initialization and acquired on open. Fixed to 0x5A494E435F524547, which spells "ZINC_REG" in ASCII. Checked on open to detect corrupted regions or segments that were overwritten by non-Zinc code. Any process could theoretically write a valid magic number at this offset; this field is a sanity check, not a security boundary.

version (offset 8, 2 bytes)

Currently 2. Incremented when the header layout changes in a backward-incompatible way. When a region is opened, the opener’s library version must match the stored version. A mismatch returns CorruptedRegion.

flags (offset 10, 2 bytes)

Reserved for future use. Currently always 0. Writers should not depend on this field being zero, as future versions may use it for feature flags.

notify_seq (offset 12, 4 bytes)

The atomic counter used by notify() and wait(). Incremented on every notify() call. On Linux, the address of this field is passed as the futex word. On other platforms, it is polled in the adaptive wait loop.

capacity (offset 16, 8 bytes)

The number of usable bytes in the data area. Set at creation time and immutable for the lifetime of the region. This is the total mapping size minus one system page.

ref_count (offset 24, 4 bytes)

Tracks the number of open handles on this region. Incremented on zinc_open, decremented on zinc_close. The creator unlinks the name when it closes, regardless of this count. Process crashes can leave an inaccurate count.

owner_pid (offset 28, 4 bytes)

The PID of the process that called create. Stored for diagnostic purposes. Not used by the library logic, but helpful when debugging leaked regions.

created_at (offset 32, 8 bytes)

Unix timestamp in nanoseconds at the time of creation. Set from SystemTime::now().duration_since(UNIX_EPOCH). Useful for ordering or deduplication of regions with the same name.

name_hash (offset 40, 8 bytes)

FNV-1a hash of the region name. Stored for diagnostics and possible future use. Name lookup uses the full POSIX name, so hash collisions do not merge regions. The hash is not an authentication or integrity check.

ring_head / ring_tail (offset 48 / 56, 8 bytes each)

Reserved atomic cursors for caller-managed ring storage. SharedRegion does not initialize or use a ring in its data area. notify and wait use only notify_seq.

Stability guarantees

The header layout is versioned. The current header version is 2. If a future version needs to add fields, it can reuse the reserved flags field or extend into the data area with a new version number. The magic and version fields are always at offset 0 and 8 for forward compatibility.

Access from user code

There is no public API to read the header fields from adapter code. The header is an internal implementation detail. However, if you need to inspect it for debugging (for example, to verify that two processes see the same header), you can read the raw bytes at offset 0 through the data pointer:

// Rust: read the header directly (unsafe, for debugging only)
let page = unsafe { libc::sysconf(libc::_SC_PAGESIZE) as usize };
let hdr: &RegionHeader = unsafe {
    &*(region.as_ptr().sub(page) as *const RegionHeader)
};
println!("magic: 0x{:x}, owner_pid: {}", hdr.magic.load(std::sync::atomic::Ordering::Acquire), hdr.owner_pid.load(std::sync::atomic::Ordering::Relaxed));

This is not recommended in production code. Changes to this layout require a header version bump.