| .TH XPAK 5 "Apr 2009" "Portage VERSION" "Portage" |
| .SH NAME |
| xpak \- The XPAK Data Format |
| .SH NOTES |
| .SS Data Types |
| .IP Integer |
| every offset or length(len) value in this documentation will be an unsigned |
| 32bit integer in big endian byte order(32bit unsigned big int or uint32(big) |
| ). |
| .IP String |
| All strings, mentioned in this documentation are ASCII encoded, and not |
| nullterminated |
| .IP Values |
| The actual values of the individual xpak entries are stored as Strings. |
| .P |
| .SS Vertical Bars |
| The vertical bars '|' are not part of the file format, they are merely used to |
| illustrate how the offset values apply to the data. |
| |
| .SH SYNOPSIS |
| |
| .IP tarball |
| |<-xpak_offset->| |
| .br |
| <tar>|< xpak >|<xpak_offset>"STOP" |
| |
| .IP xpak |
| "XPAKPACK"<index_len><data_len><index><data>"XPAKSTOP" |
| |
| .IP index |
| |<-------------index_len------------->| |
| .br |
| |<index1><index2><index3><index4><...>| |
| |
| .IP indexN |
| |<-name_len->| |
| .br |
| <name_len>|< name >|<data_offset><data_len> |
| |
| .IP data |
| |<--------------data_len------------->| |
| .br |
| |<-dataN_offset->|<-dataN_len->| |
| .br |
| |< data >|< data_N >|<data>| |
| |
| .SH DETAILED |
| Every gentoo binary package has a xpak attached to it which contains build |
| time information like the use flags it was built with, the ebuild it was |
| built from, the environmental variables, CFLAGs, CXXFLAGs, .... |
| |
| .SS xpak |
| |
| If you look at a gentoo binary package (binpkg) with a hex-editor you'll |
| notice the behinf the data, which belongs to the tarball you find a binary |
| blob - the |
| .I xpak |
| , an offset which holds the bytes from the start of the |
| .I xpak |
| to the end of the file - |
| .I xpak_offset |
| and finally the String |
| .I "STOP". |
| |
| |<xpak_offset>| |
| <tbz2>|<---xpak---->|<xpak_offset>"STOP"| |
| |
| Here you see the |
| .I tbz2 |
| archive, and the attached |
| .I xpak |
| blob, the |
| .I xpak-offset |
| and |
| the string |
| .I "STOP" |
| at the end. |
| |
| If we read the offset value and count |
| .I offset |
| bytes backwards from the start of |
| .I xpak_offset |
| , we have found the start of the |
| .I xpak |
| Block which starts with the String |
| .I "XPAKPACK". |
| This xpak block consists of the string |
| .I "XPAKPACK" |
| , the length of the |
| .I index |
| block - |
| .I index-len |
| , the length of the data block - |
| .I data-len |
| , an |
| .I index-len |
| bytes long binary blob with the |
| .I index |
| , a |
| .I data-len |
| bytes long binary blob with the |
| .I data |
| and the string |
| .I "XPAKSTOP" |
| at the end: |
| |
| |<index_len>|<data_len>| |
| "XPAKPACK"<index_len><data_len>|<--index-->|<--data-->|"XPAKSTOP" |
| |
| To actually get the |
| .I index |
| and the |
| .I data |
| , we cut out |
| .I index_len |
| bytes after the end of |
| .I data_len |
| for the index block and then cut out the next |
| .I data_len |
| bytes for the data block. If we have done everything right up to this point, |
| the following bytes would be the ASCII formatted string |
| .I "XPAKSTOP" |
| . |
| |
| The actual data is truncated into one big block - so if we want to read it we |
| need the actual positions of each information in this big data block, this |
| information can be obtained using the indices which are stored in the |
| .I index |
| block. |
| |
| .SS Index block |
| The index block consists of several truncated index blocks: |
| |
| |<-----------------------index_len---------------------->| |
| |<index1><index2><index3><index4><index5><index6><index7>| |
| |
| The |
| .I index |
| block holds all information we need to find the data we want in the |
| .I data |
| block. It consists of truncated index elements with a length |
| .I index_len. |
| Each of those index elements stands for one information in the data block and |
| consists of the length of its name ( |
| .I name_len> |
| ), a |
| .I name_len |
| bytes long string (the Name of the data block), this index belongs to, the |
| offset of the |
| .I data |
| block ( |
| .I data_offset |
| ) and the length of that data block ( |
| .I data_len |
| ): |
| |
| |<name_len>| |
| <name_len>|<--name-->|<dataN_offset><dataN_len> |
| |
| .SS Data block |
| the data block contains truncated data blocks with a total length of |
| .I data_len |
| : |
| |
| |<------------------------data_len------------------------>| |
| |<data1><data2><data3><data4><data5><data6><data7><data...>| |
| |
| This binary block is |
| .I data_len |
| bytes long and consists of truncated data. |
| |
| To select one data element, we need the |
| .I data_offset |
| and the |
| .I data_len |
| from |
| the |
| .I index |
| , if we have those we can count |
| .I data_offset |
| bytes from the start of the |
| .I data |
| block, and then cut out the next |
| .I data_len |
| bytes. there we got our data block: |
| |
| |<-----dataN_offset----->|<--dataN_len->| |
| |<data1data2data3data...>|<data-we-want>| |
| .SH AUTHORS |
| Lars Hartmann <lars@chaotika.org> |
| .SH "SEE ALSO" |
| .BR qtbz2 (1), |
| .BR quickpkg (1), |
| .BR qxpak (1) |