From 4478801fe3857d127023e8c46d5f3f7020972ab4 Mon Sep 17 00:00:00 2001 From: Zac Medico Date: Wed, 11 Mar 2009 08:07:21 +0000 Subject: Add new xpak.5 man page by Lars Hartmann chaotikaorg>. svn path=/main/trunk/; revision=13056 --- man/xpak.5 | 190 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 man/xpak.5 (limited to 'man') diff --git a/man/xpak.5 b/man/xpak.5 new file mode 100644 index 000000000..22667dc67 --- /dev/null +++ b/man/xpak.5 @@ -0,0 +1,190 @@ +.TH XPAK 5 "March 2009" "Portage 2.2" "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 +|< xpak >|"STOP" + +.IP xpak +"XPAKPACK""XPAKSTOP" + +.IP index +|<-------------index_len------------->| +.br +|<...>| + +.IP indexN + |<-name_len->| +.br +|< name >| + +.IP data +|<--------------data_len------------->| +.br +|<-dataN_offset->|<-dataN_len->| +.br +|< data >|< data_N >|| + +.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---->|"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: + + ||| + "XPAKPACK"|<--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---------------------->| + || + +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-->| + +.SS Data block +the data block contains truncated data blocks with a total length of +.I data_len +: + + |<------------------------data_len------------------------>| + || + +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->| + ||| +.SH AUTHORS +Lars Hartmann chaotikaorg> -- cgit v1.2.3-1-g7c22