luci-app-adblock: sync with adblock 3.5.2
[project/luci.git] / documentation / LAR.md
1 LAR is a simple archive format to pack multiple lua source files and arbitrary other resources into a single file.
2
3
4 # Format Specification
5
6 A LAR archive file is divided into two parts: the payload and the index lookup table.
7 All segments of the archive are 4 Byte aligned to ease reading and processing of the format.
8 All integers are stored in network byte order, so an implementation has to use htonl() and htons() to properly read them.
9
10 Schema:
11         
12         <payload:
13           <member:
14             <N*4 bytes: path of file #1>
15             <N*4 bytes: data of file #1>
16           >
17           
18           <member:
19             <N*4 bytes: path of file #2>
20             <N*4 bytes: data of file #2>
21           >
22         
23           ...
24         
25           <member:
26             <N*4 bytes: path of file #N>
27             <N*4 bytes: data of file #N>
28           >
29         >
30         
31         <index table:
32           <entry:
33             <uint32: offset for path of file #1> <uint32: length for path of file #1>
34             <uint32: offset for data of file #1> <uint32: length for data of file #1>
35             <uint16: type of file #1> <uint16: flags of file #1>
36           >
37         
38           <entry:
39             <uint32: offset for path of file #2> <uint32: length for path of file #2>
40             <uint32: offset for data of file #2> <uint32: length for data of file #2>
41             <uint16: type of file #2> <uint16: flags of file #2>
42           >
43         
44           ...
45         
46           <entry:
47             <uint32: offset for path of file #N> <uint32: length for path of file #N>
48             <uint32: offset for data of file #N> <uint32: length for data of file #N>
49             <uint16: type of file #N> <uint16: flags of file #N>
50           >
51         >
52         
53         <uint32: offset for begin of index table>
54         
55
56
57 # Processing
58
59 In order to process an LAR archive, an implementation would have to do the following steps:
60
61 ## Read Index
62
63 1. Locate and open the archive file
64 1. Seek to end of file - 4 bytes
65 1. Read 32bit index offset and swap from network to native byte order
66 1. Seek to index offset, calculate index length: filesize - index offset - 4
67 1. Initialize a linked list for index table entries
68 1. Read each index entry until the index length is reached, read and byteswap 4 * 32bit int and 2 * 16bit int
69 1. Seek to begin of file
70
71 ## Read Member
72
73 1. Read the archive index
74 1. Iterate through the linked index list, perform the following steps for each entry
75 1. Seek to the specified file path offset
76 1. Read as much bytes as specified in the file path length into a buffer
77 1. Compare the contents of the buffer against the path of the searched member
78 1. If buffer and searched path are equal, seek to the specified file data offset
79 1. Read data until the file data length is reached, return
80 1. Select the next index table entry and repeat from step 3, if there is no next entry then return
81
82 # Reference implementation
83
84 A reference implementation can be found here:
85 http://luci.subsignal.org/trac/browser/luci/trunk/contrib/lar
86
87 The lar.pl script is a simple packer for LAR archives and cli.c provides a utility to list and dump packed LAR archives.