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