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.