github.com/sashka/siva@v1.6.0/SPEC.md (about)

     1  
     2  ## Specification
     3  
     4  This is the specification of the siva format version 1.
     5  
     6  A siva file is composed of a sequence of one or more blocks. Blocks are just
     7  concatenated without any additional delimiter.
     8  
     9  ```
    10  block 1
    11  ...
    12  [block n]
    13  ```
    14  
    15  ### Block
    16  
    17  Each block has the following structure:
    18  
    19  ```
    20  [file content 1]
    21  ...
    22  [file content n]
    23  index
    24  ```
    25  
    26  The content of each file is concatenated without any delimiter. After the last
    27  file content, there is an index of the block.
    28  
    29  It is possible to have a block with no file contents at all. That is the case
    30  for a block that deletes a file. In any case, the index must be present.
    31  
    32  ### Index
    33  
    34  The index has the following structure:
    35  
    36  ```
    37  signature
    38  version
    39  [index entry 1]
    40  ...
    41  [index entry n]
    42  [index footer]
    43  ```
    44  
    45  The `signature` field is a sequence of 3 bytes (Go implementation use uint8 for this. Go byte is an alias for uint8 type) with the value `IBA`. If the
    46  signature does not match this sequence, it is considered an error.
    47  
    48  The `version` field is an uint8 with the value `1`. If the version contains an
    49  unknown value, the implementation is not expected to be able to read the file
    50  at all.
    51  
    52  Each index entry has the following fields:
    53  
    54  * Byte length of the entry name (uint32).
    55  * Entry name (UTF-8 string in UNIX format).
    56  * UNIX mode (uint32), [see below](#unix-mode-format).
    57  * Modification time as UNIX time in nanoseconds (int64).
    58  * Offset of the file content, relative to the beginning of the block (uint64).
    59  * Size of the file content (uint64).
    60  * CRC32 (uint32) (Integrity of the file content this entry points to).
    61  * Flags (uint32), supported flags: 0x0 (no flags), 0x1 (deleted).
    62  
    63  The index footer consists of:
    64  
    65  * Number of entries in the block (uint32).
    66  * Index size in bytes (uint64).
    67  * Block size in bytes (uint64).
    68  * CRC32 (uint32) (Integrity of: Signature + Version + Entries).
    69  
    70  All integers are encoded as big endian.
    71  
    72  ### Unix Mode Format
    73  
    74  The UNIX mode field has the following format:
    75  
    76  ```
    77       3 3 2 2 2 2 2 2 2 2 2 2 1 1 1 1 1 1 1 1 1 1
    78  bit  1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0 9 8 7 6 5 4 3 2 1 0
    79    M +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ L
    80    S |d|a|l|T|L|D|p|S|u|g|c|t|?| - - - - - - - - - |r|w|x|r|w|x|r|w|x| S
    81    B +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ B
    82       @ _ _ _ @ @ @ @ _ _ @ _ @  ← file type bits  |owner|group|other|
    83       | | | | | | | | | | | | | 	                     access perms
    84       | | | | | | | | | | | | |- non-regular file
    85       | | | | | | | | | | | \--- sticky
    86       | | | | | | | | | | \----- character device (when D is set)
    87       | | | | | | | | | \------- setgid
    88       | | | | | | | | \--------- setuid
    89       | | | | | | | \----------- Unix-domain socket
    90       | | | | | | \------------- named pipe (FIFO)
    91       | | | | | \--------------- device file
    92       | | | | \----------------- symbolic link
    93       | | | \------------------- temporary file (Plan 9 only)
    94       | | \--------------------- exclusive use
    95       | \----------------------- append-only
    96       \------------------------- directory
    97  ```
    98  
    99  All the bits not otherwise labelled are reserved for future use.
   100  
   101  **Note:** This layout is defined by the [Go `os` package](https://godoc.org/os#FileMode)
   102  and is _not_ the same layout as POSIX. The same layout is used on all
   103  systems. See [issue #11](https://github.com/src-d/go-siva/issues/11) for
   104  context.
   105  
   106  ## Limitations
   107  
   108  The following limits apply to the format as of version 1:
   109  
   110  * File name length: 2<sup>32</sup>-1 bytes.
   111  * Number of blocks: no limit.
   112  * Number of entries per block: 2<sup>32</sup>-1
   113  * Number of total entries: no limit (reference implementation does not support more than 2<sup>63</sup>-1).
   114  * Block index size: 2<sup>64</sup>-1 bytes.
   115  * Block size: 2<sup>64</sup>-1 bytes.
   116  * File entry size: 2<sup>64</sup>-1 bytes.
   117  * Archive file size: no limit.