man/xpak.5

   1 .TH XPAK 5 "March 2009" "Portage VERSION" "Portage"
   2 .SH NAME
   3 xpak \- The XPAK Data Format
   4 .SH NOTES
   5 .SS Data Types
   6 .IP Integer
   7 every offset or length(len) value in this documentation will be an unsigned
   8 32bit integer in big endian byte order(32bit unsigned big int or uint32(big)
   9 ).
  10 .IP String
  11 All strings, mentioned in this documentation are ASCII encoded, and not
  12 nullterminated
  13 .IP Values
  14 The actual values of the individual xpak entries are stored as Strings.
  15 .P
  16 .SS Vertical Bars
  17 The vertical bars '|' are not part of the file format, they are merely used to
  18 illustrate how the offset values apply to the data.
  19
  20 .SH SYNOPSIS
  21
  22 .IP tarball
  23      |<-xpak_offset->|
  24 .br
  25 <tar>|<    xpak     >|<xpak_offset>"STOP"
  26
  27 .IP xpak
  28 "XPAKPACK"<index_len><data_len><index><data>"XPAKSTOP"
  29
  30 .IP index
  31 |<-------------index_len------------->|
  32 .br
  33 |<index1><index2><index3><index4><...>|
  34
  35 .IP indexN
  36           |<-name_len->|
  37 .br
  38 <name_len>|<   name   >|<data_offset><data_len>
  39
  40 .IP data
  41 |<--------------data_len------------->|
  42 .br
  43 |<-dataN_offset->|<-dataN_len->|
  44 .br
  45 |<     data     >|<  data_N   >|<data>|
  46
  47 .SH DETAILED
  48 Every gentoo binary package has a xpak attached to it which contains build
  49 time information like the use flags it was built with, the ebuild it was
  50 built from, the environmental variables, CFLAGs, CXXFLAGs, ....
  51
  52 .SS xpak
  53
  54 If you look at a gentoo binary package (binpkg) with a hex-editor you'll
  55 notice the behinf the data, which belongs to the tarball you find a binary
  56 blob - the
  57 .I xpak
  58 , an offset which holds the bytes from the start of the
  59 .I xpak
  60 to the end of the file -
  61 .I xpak_offset
  62 and finally the String
  63 .I "STOP".
  64
  65        |<xpak_offset>|
  66  <tbz2>|<---xpak---->|<xpak_offset>"STOP"|
  67
  68 Here you see the
  69 .I tbz2
  70 archive, and the attached
  71 .I xpak
  72 blob, the
  73 .I xpak-offset
  74 and
  75 the string
  76 .I "STOP"
  77 at the end.
  78
  79 If we read the offset value and count
  80 .I offset
  81 bytes backwards from the start of
  82 .I xpak_offset
  83 , we have found the start of the
  84 .I xpak
  85 Block which starts with the String
  86 .I "XPAKPACK".
  87 This xpak block consists of the string
  88 .I "XPAKPACK"
  89 , the length of the
  90 .I index
  91 block -
  92 .I index-len
  93 , the length of the data block -
  94 .I data-len
  95 , an
  96 .I index-len
  97 bytes long binary blob with the
  98 .I index
  99 , a
 100 .I data-len
 101 bytes long binary blob with the
 102 .I data
 103 and the string
 104 .I "XPAKSTOP"
 105 at the end:
 106
 107                                 |<index_len>|<data_len>|
 108  "XPAKPACK"<index_len><data_len>|<--index-->|<--data-->|"XPAKSTOP"
 109
 110 To actually get the
 111 .I index
 112 and the
 113 .I data
 114 , we cut out
 115 .I index_len
 116 bytes after the end of
 117 .I data_len
 118  for the index block and then cut out the next
 119 .I data_len
 120 bytes for the data block. If we have done everything right up to this point,
 121 the following bytes would be the ASCII formatted string
 122 .I "XPAKSTOP"
 123 .
 124
 125 The actual data is truncated into one big block - so if we want to read it we
 126 need the actual positions of each information in this big data block, this
 127 information can be obtained using the indices which are stored in the
 128 .I index
 129 block.
 130
 131 .SS Index block
 132 The index block consists of several truncated index blocks:
 133
 134  |<-----------------------index_len---------------------->|
 135  |<index1><index2><index3><index4><index5><index6><index7>|
 136
 137 The
 138 .I index
 139 block holds all information we need to find the data we want in the
 140 .I data
 141 block. It consists of truncated index elements with a length
 142 .I index_len.
 143 Each of those index elements stands for one information in the data block and
 144 consists of the length of its name (
 145 .I name_len>
 146 ), a
 147 .I name_len
 148  bytes long string (the Name of the data block), this index belongs to, the
 149 offset of the
 150 .I data
 151 block (
 152 .I data_offset
 153 ) and the length of that data block (
 154 .I data_len
 155 ):
 156
 157            |<name_len>|
 158  <name_len>|<--name-->|<dataN_offset><dataN_len>
 159
 160 .SS Data block
 161 the data block contains truncated data blocks with a total length of
 162 .I data_len
 163 :
 164
 165  |<------------------------data_len------------------------>|
 166  |<data1><data2><data3><data4><data5><data6><data7><data...>|
 167
 168 This binary block is
 169 .I data_len
 170 bytes long and consists of truncated data.
 171
 172 To select one data element, we need the
 173 .I data_offset
 174 and the
 175 .I data_len
 176 from
 177 the
 178 .I index
 179 , if we have those we can count
 180 .I data_offset
 181 bytes from the start of the
 182 .I data
 183 block, and then cut out the next
 184 .I data_len
 185 bytes. there we got our data block:
 186
 187  |<-----dataN_offset----->|<--dataN_len->|
 188  |<data1data2data3data...>|<data-we-want>|
 189 .SH AUTHORS
 190 Lars Hartmann <lars@chaotika.org>
 191 .SH "SEE ALSO"
 192 .BR qtbz2 (1),
 193 .BR quickpkg (1),
 194 .BR qxpak (1)