Struct Layouts

Byte-level layouts for all structures crossing the kernel/userspace boundary. Kernel/userspace syscall and ioctl argument structures use natural C layout with fixed-width fields and explicit padding fields. They are not packed with #pragma pack or __attribute__((packed)). The offsets and totals shown below are normative for the supported little-endian ABI. GUIDs are 16 bytes, stored as raw bytes (not a struct of fields).

Variable byte records such as watch events, RSI frames, and backup records are raw offset-defined byte streams rather than C structs. They may be unaligned; consumers parse them using the offsets in this specification.

An independent implementer can write compatible userspace code from this page.

Strings in ioctl structs are length-delimited, not null-terminated. Each string is referenced by a (len, ptr) pair where len is the byte count and ptr is a uint64 userspace address. LCS reads exactly len bytes from ptr. Null terminators are neither required nor expected.

§11.2.1 Reserved and padding fields #

All fields named _pad, reserved, or otherwise described as reserved are ABI extension points. On every syscall or ioctl input structure, callers MUST set these fields to zero. LCS MUST reject the operation with EINVAL if any reserved or padding input field is non-zero. This validation occurs before source dispatch, transaction enlistment, sequence allocation, or output copy.

For kernel-produced output structures and watch events, LCS MUST zero every reserved or padding byte before copying data to userspace. Future versions may define semantics for reserved fields; older kernels must not silently accept non-zero values whose meaning they do not understand.

Any flags field in a kernel-facing ABI structure MUST contain only the bits defined for that field. Unknown or reserved flag bits fail with EINVAL unless the field-specific text explicitly defines a different rule.

§11.2.2 Variable-size output buffer probes #

Ioctls that return variable-size data use the uniform two-pass ABI defined in §6.3. A (len = 0, ptr = NULL) output buffer is a valid probe. A (len = 0, ptr != NULL) output buffer is also treated as a probe and the pointer is ignored. If len > 0, ptr must be non-null and writable for len bytes or the ioctl fails with EFAULT. On ERANGE, required size fields are updated, output buffers are not partially filled, and output scalar metadata is valid only when explicitly documented for ERANGE.

§11.2.3 Syscall argument structs #

§11.2.3.1 reg_create_key_args #

The path and layer fields retain the syscall string convention from §6.2: they are pointers to null-terminated userspace strings, not length-delimited ioctl strings.

Total: 48 bytes.

§11.2.4 Ioctl argument structs #

§11.2.4.1 reg_query_value_args (REG_IOC_QUERY_VALUE) #

Total: 64 bytes.

If data_len on input is too small, the ioctl returns ERANGE and sets data_len to the required size. If the layer-name buffer is too small, layer_len is set to the required size. If both are too small, both required sizes are reported. The caller retries with larger buffers.

§11.2.4.2 reg_set_value_args (REG_IOC_SET_VALUE) #

Total: 64 bytes.

§11.2.4.3 reg_delete_value_args (REG_IOC_DELETE_VALUE) #

Total: 40 bytes.

§11.2.4.4 reg_blanket_tombstone_args (REG_IOC_BLANKET_TOMBSTONE) #

Total: 24 bytes.

§11.2.4.5 reg_query_values_batch_args (REG_IOC_QUERY_VALUES_BATCH) #

Total: 24 bytes.

Each value in the buffer is packed as:

Values are packed consecutively with no padding between them. If the buffer is too small, the ioctl returns ERANGE and sets buf_len to the required size.

§11.2.4.6 reg_enum_value_args (REG_IOC_ENUM_VALUES) #

Total: 40 bytes.

§11.2.4.7 reg_enum_subkey_args (REG_IOC_ENUM_SUBKEYS) #

Total: 40 bytes.

§11.2.4.8 reg_query_key_info_args (REG_IOC_QUERY_KEY_INFO) #

Total: 64 bytes.

§11.2.4.9 reg_delete_key_args (REG_IOC_DELETE_KEY) #

Total: 24 bytes.

§11.2.4.10 reg_hide_key_args (REG_IOC_HIDE_KEY) #

Total: 24 bytes.

§11.2.4.11 reg_get_security_args (REG_IOC_GET_SECURITY) #

Total: 16 bytes.

§11.2.4.12 reg_set_security_args (REG_IOC_SET_SECURITY) #

Total: 24 bytes.

§11.2.4.13 reg_notify_args (REG_IOC_NOTIFY) #

Total: 8 bytes.

§11.2.4.14 reg_backup_args (REG_IOC_BACKUP) #

Total: 4 bytes.

§11.2.4.15 reg_restore_args (REG_IOC_RESTORE) #

Total: 4 bytes.

§11.2.4.16 reg_txn_status_args (REG_IOC_TXN_STATUS) #

Total: 8 bytes.

§11.2.5 Security information flags #

Used in reg_get_security_args and reg_set_security_args:

security_info values passed to REG_IOC_GET_SECURITY and REG_IOC_SET_SECURITY MUST be non-zero subsets of these four flags. Unknown bits fail with EINVAL.

§11.2.6 Watch event structures #

§11.2.6.1 Direct watch event #

Minimum size: 8 bytes (no name).

§11.2.6.2 Subtree watch event #

Extends the direct event with path components:

path_depth of 0 means the change is on the watched key itself (equivalent to a direct event). Consumers distinguish direct from subtree events by checking whether bytes remain after the name field (using total_len).

§11.2.7 RSI registration struct #

§11.2.7.1 reg_src_register_args (REG_SRC_REGISTER ioctl) #

Total: 24 bytes.

§11.2.7.2 reg_src_hive_entry #

Total: 56 bytes per entry.