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.