% limb manual
% patrim(5)
% limb 0.1.0
% 2023-07-24

# NAME

PATRIM - the pack-trimmed format

# DESCRIPTION

The PATRIM format is a simple format that allows to store data in binary form,
where every data is identified by an ID, that represents either an unsigned
integer or a blob/byte array.

Data are stored very simply : first the ID, then either the value for an
integer, or the data length for a blob, in which case said data must immediately
follow.

IDs and values/lengths are stored using the "pack trimmed" algorithm, as
described in [u64_pack_trim](3). Meaning the value is stored in little endian
mode, but only the low 7 bits are used for the value, the most significant bit
being a flag which, when set, indicates that another byte must be read and
processed.

Any 64bit number can be written that way, packed into from 1 to 9 bytes,
depending on the actual value.

The IDs are unsigned numbers to identify their associated value, with the least
significant bit having a special meaning : if set, it represents a blob,
otherwise an (unsigned) integer.

! HINT:
! Helpers functions are available, either directly (e.g. [patrim_put](3)) or
! when using a buffer (e.g. [buffer_patrim_put](3)).

That is all.

# FILE FORMATS

As a rule, any file whose content is encoded in PATRIM should first feature an
header as such :

- A big-endian encoded 32bit magic number, to identify the specific file format.
  The magic number should have certain bits set to indicate it is PATRIM
  encoded, specifically : `(magic & 0xf0f0f000) = 0xa0e0f000`
- Additionally, bit 8 is used as a flag to indicate whether or not the file
  contains shielded data, as described in [shldata](5).
  When set, and shielded data are present, for every ID in the file its bit 7 is
  a flag which, when set, indicates the data are part of the shielded data
  protocol itself.
- A version number, pack-trimmed.

Helpers functions [buffer_puthdr](3) and [buffer_gethdr](3) are available to
write and read such headers, respectively.