summaryrefslogtreecommitdiffhomepage
path: root/documentation/LAR.md
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/LAR.md')
-rw-r--r--documentation/LAR.md87
1 files changed, 87 insertions, 0 deletions
diff --git a/documentation/LAR.md b/documentation/LAR.md
new file mode 100644
index 000000000..f44d8dc7d
--- /dev/null
+++ b/documentation/LAR.md
@@ -0,0 +1,87 @@
+LAR is a simple archive format to pack multiple lua source files and arbitary other resources into a single file.
+
+
+# Format Specification
+
+A LAR archive file is divided into two parts: the payload and the index lookup table.
+All segments of the archive are 4 Byte aligned to ease reading and processing of the format.
+All integers are stored in network byte order, so an implementation has to use htonl() and htons() to properly read them.
+
+Schema:
+
+ <payload:
+ <member:
+ <N*4 bytes: path of file #1>
+ <N*4 bytes: data of file #1>
+ >
+
+ <member:
+ <N*4 bytes: path of file #2>
+ <N*4 bytes: data of file #2>
+ >
+
+ ...
+
+ <member:
+ <N*4 bytes: path of file #N>
+ <N*4 bytes: data of file #N>
+ >
+ >
+
+ <index table:
+ <entry:
+ <uint32: offset for path of file #1> <uint32: length for path of file #1>
+ <uint32: offset for data of file #1> <uint32: length for data of file #1>
+ <uint16: type of file #1> <uint16: flags of file #1>
+ >
+
+ <entry:
+ <uint32: offset for path of file #2> <uint32: length for path of file #2>
+ <uint32: offset for data of file #2> <uint32: length for data of file #2>
+ <uint16: type of file #2> <uint16: flags of file #2>
+ >
+
+ ...
+
+ <entry:
+ <uint32: offset for path of file #N> <uint32: length for path of file #N>
+ <uint32: offset for data of file #N> <uint32: length for data of file #N>
+ <uint16: type of file #N> <uint16: flags of file #N>
+ >
+ >
+
+ <uint32: offset for begin of index table>
+
+
+
+# Processing
+
+In order to process an LAR archive, an implementation would have to do the following steps:
+
+## Read Index
+
+1. Locate and open the archive file
+1. Seek to end of file - 4 bytes
+1. Read 32bit index offset and swap from network to native byte order
+1. Seek to index offset, calculate index length: filesize - index offset - 4
+1. Initialize a linked list for index table entries
+1. Read each index entry until the index length is reached, read and byteswap 4 * 32bit int and 2 * 16bit int
+1. Seek to begin of file
+
+## Read Member
+
+1. Read the archive index
+1. Iterate through the linked index list, perform the following steps for each entry
+1. Seek to the specified file path offset
+1. Read as much bytes as specified in the file path length into a buffer
+1. Compare the contents of the buffer against the path of the searched member
+1. If buffer and searched path are equal, seek to the specified file data offset
+1. Read data until the file data length is reached, return
+1. Select the next index table entry and repeat from step 3, if there is no next entry then return
+
+# Reference implementation
+
+A reference implementation can be found here:
+http://luci.subsignal.org/trac/browser/luci/trunk/contrib/lar
+
+The lar.pl script is a simple packer for LAR archives and cli.c provides a utility to list and dump packed LAR archives.