man/xpak.5

   1 .TH XPAK 5 "Oct 2011" "Portage VERSION" "Portage"
   2 .SH NAME
   3 xpak \- The XPAK Data Format used with Portage binary packages
   4 .SH DESCRIPTION
   5 Every Gentoo binary package has a xpak attached to it which contains build
   6 time information like the USE flags it was built with, the ebuild it was
   7 built from, the environmental variables, CFLAGS, CXXFLAGS, etc...
   8 .SH NOTES
   9 .SS Data Types
  10 The following conventions cover all occurrences in this documentation
  11 .IP Integer
  12 All offsets/lengths are big endian unsigned 32bit integers
  13 .IP String
  14 All strings are ASCII encoded, and not NUL terminated (quotes are for
  15 illustration only)
  16 .IP Values
  17 The actual values of the individual xpak entries are stored as Strings
  18 .P
  19 .SS Vertical Bars
  20 The vertical bars '|' are not part of the file format; they are merely used to
  21 illustrate how the offset values apply to the data.
  22 .SH SYNOPSIS
  23 .IP "binpkg (tbz2)"
  24       |<-xpak_offset->|
  25  <tar>|<    xpak     >|<xpak_offset>"STOP"
  26 .IP xpak
  27  "XPAKPACK"<index_len><data_len><index><data>"XPAKSTOP"
  28 .IP index
  29  |<-------------index_len------------->|
  30  |<index1><index2><index3><index4><...>|
  31 .IP indexN
  32            |<-name_len->|
  33  <name_len>|<   name   >|<data_offset><data_len>
  34 .IP data
  35  |<--------------data_len------------->|
  36  |<-dataN_offset->|<-dataN_len->|
  37  |<     data     >|<  data_N   >|<data>|
  38 .SH DETAILS
  39 .SS xpak
  40
  41 If you look at a Gentoo binary package (binpkg) with a hex-editor you'll
  42 notice that after the tarball of files, you find a binary blob - the
  43 \fIxpak\fR, an offset which holds the bytes from the start of the
  44 \fIxpak\fR to the end of the file - \fIxpak_offset\fR and finally the
  45 String \fI"STOP"\fR.
  46
  47       |<xpak_offset>|
  48  <tar>|<---xpak---->|<xpak_offset>"STOP"
  49
  50 Here you see the \fItar\fR archive, the attached \fIxpak\fR blob, the
  51 \fIxpak_offset\fR and the string \fI"STOP"\fR at the end.  This metadata
  52 is not considered "part" of the \fIxpak\fR, but rather part of the binpkg.
  53
  54 If we read the offset value and count \fIoffset\fR bytes backwards from
  55 the start of \fIxpak_offset\fR, we have found the start of the \fIxpak\fR
  56 block which starts with the String \fI"XPAKPACK"\fR.
  57
  58 This xpak block consists of the string \fI"XPAKPACK"\fR, the length of the
  59 \fIindex\fR block (\fIindex_len\fR), the length of the \fIdata\fR block
  60 (\fIdata_len\fR), an \fIindex_len\fR bytes long binary blob with the
  61 \fIindex\fR, a \fIdata_len\fR bytes long binary blob with the \fIdata\fR,
  62 and the string \fI"XPAKSTOP"\fR at the end:
  63
  64                                 |<index_len>|<data_len>|
  65  "XPAKPACK"<index_len><data_len>|<--index-->|<--data-->|"XPAKSTOP"
  66
  67 To actually get the \fIindex\fR and the \fIdata\fR, we cut out \fIindex_len\fR
  68 bytes after the end of \fIdata_len\fR for the \fIindex\fR block, and then cut
  69 out the next \fIdata_len\fR bytes for the \fIdata\fR block.  If we have done
  70 everything right up to this point, the following bytes would be the ASCII
  71 formatted string \fI"XPAKSTOP"\fR.
  72
  73 The actual \fIdata\fR is merged into one big block; so if we want to read it,
  74 we need the actual positions of each information in this big data block.  This
  75 information can be obtained using the indices which are stored in the
  76 \fIindex\fR block.
  77
  78 .SS Index block
  79 The \fIindex\fR block consists of several indices:
  80
  81  |<-----------------------index_len---------------------->|
  82  |<index1><index2><index3><index4><index5><index6><index7>|
  83
  84 The \fIindex\fR block holds all the information we need to find the data we
  85 want in the \fIdata\fR block.  It consists of multiple index elements, all of
  86 which add up to the total length \fIindex_len\fR.  It is not zero delimited
  87 or anything else.
  88
  89 Each of those elements corresponds to one chunk of data in the \fIdata\fR
  90 block: the length of that block's name (\fIname_len\fR), a \fIname_len\fR
  91 bytes long string, the offset of that block (\fIdataN_offset\fR) and the
  92 length of that block (\fIdataN_len\fR):
  93
  94            |<name_len>|
  95  <name_len>|<--name-->|<dataN_offset><dataN_len>
  96
  97 .SS Data block
  98 The \fIdata\fR block contains multiple chunks of data with a total length of
  99 \fIdata_len\fR:
 100
 101  |<------------------------data_len------------------------>|
 102  |<data1><data2><data3><data4><data5><data6><data7><data...>|
 103
 104 To select one data element, we need the \fIdata_offset\fR and the
 105 \fIdata_len\fR from the \fIindex\fR.  With those, we can count
 106 \fIdata_offset\fR bytes from the start of the \fIdata\fR block,
 107 and then cut out the next \fIdata_len\fR bytes.  Then we got our
 108 data block:
 109
 110  |<-----dataN_offset----->|<--dataN_len->|
 111  |<data1data2data3data...>|<data-we-want>|
 112 .SH EXAMPLES
 113 Let's say we have an xpak with two chunks of data.  The first has the name
 114 "file1" with the contents "ddDddDdd" and the second has the name "file2" with
 115 the contents "jjJjjJjj".  There is no \fI"STOP"\fR or \fIxpak_offset\fR as
 116 this xpak is not part of a binpkg.
 117
 118 Here is the hexdump output (we will break it down line by line below):
 119  00  58 50 41 4b 50 41 43 4b  00 00 00 20 00 00 00 10  |XPAKPACK... ....|
 120  10  00 00 00 04 66 69 6c 31  00 00 00 00 00 00 00 08  |....fil1........|
 121  20  00 00 00 04 66 69 6c 32  00 00 00 08 00 00 00 08  |....fil2........|
 122  30  64 64 44 64 64 44 64 64  6a 6a 4a 6a 6a 4a 6a 6a  |ddDddDddjjJjjJjj|
 123  40  58 50 41 4b 53 54 4f 50                           |XPAKSTOP|
 124
 125 The \fIindex_len\fR is 32 and the \fIdata_len\fR 16 (as there are 16 bytes:
 126 "ddDddDdd" and "jjJjjJjj").
 127     |<------"XPAKPACK"----->||    32     |    16     |
 128  00  58 50 41 4b 50 41 43 4b  00 00 00 20 00 00 00 10
 129
 130 Now we have the first index element with a \fIname_len\fR of 4, followed
 131 by the name string "fil1", followed by the data1 offset of 0 and a data1
 132 len of 8 (since data1 has 8 bytes: "ddDddDdd").
 133     |     4     |<--"fil1"->||data1_off:0|data1_len:8|
 134  10  00 00 00 04 66 69 6c 31  00 00 00 00 00 00 00 08
 135
 136 Now we have the second index element with a \fIname_len\fR of 4, followed
 137 by the name string "fil2", followed by the data2 offset of 8 and a data2
 138 len of 8 (since data2 has 8 bytes: "jjJjjJjj").
 139     |     4     |<--"fil2"->||data2_off:8|data2_len:8|
 140  20  00 00 00 04 66 69 6c 32  00 00 00 08 00 00 00 08
 141
 142     |<------"XPAKSTOP"----->|
 143  40  58 50 41 4b 53 54 4f 50
 144 .SH AUTHORS
 145 .nf
 146 Lars Hartmann <lars@chaotika.org>
 147 Mike Frysinger <vapier@gentoo.org>
 148 .fi
 149 .SH "SEE ALSO"
 150 .BR qtbz2 (1),
 151 .BR quickpkg (1),
 152 .BR qxpak (1)