From: Fabian Groffen <grobian@gentoo.org>
Date: Sun, 30 Dec 2007 16:33:01 +0000 (-0000)
Subject: Because pipping doesn't understand C-code, I wrote a man-page for chpathtool so he... 
X-Git-Url: http://git.tremily.us/gitweb.cgi?a=commitdiff_plain;h=ef34f381cff8fa4ed8ebde9531ddf717af722211;p=portage.git

Because pipping doesn't understand C-code, I wrote a man-page for chpathtool so he can also understand what the tool does (try to accomplish)

svn path=/main/branches/prefix/; revision=9120
---

diff --git a/man/chpathtool.5 b/man/chpathtool.5
new file mode 100644
index 000000000..97714da97
--- /dev/null
+++ b/man/chpathtool.5
@@ -0,0 +1,59 @@
+.TH "CHPATHTOOL" "5" "Dec 2007" "Portage 2.2-prefix" "Portage"
+.SH NAME
+chpathtool \- changes paths inside files
+.SH SYNOPSIS
+.B chpathtool
+.R [-q]
+.I in-file
+.I out-file
+.I magic
+.I value
+.SH DESCRIPTION
+.B chpathtool
+is an application that changes occurences of
+.I magic
+into
+.I value
+for the given
+.I in-file
+and writes the modified file as
+.IR outfile ".
+.RB "The important difference of " chpathtool " when compared to e.g.
+.BR sed "(1)
+is that for the strings it replaces, it maintains the original string
+.RI "length of " magic " by padding the " value " string with zero
+.RI "bytes, until the size of " magic " is reached.
+.P
+.RB "For efficiency, " chpathtool " will operate recursively if
+.IR in-file " is a directory.  In that case, " out-file " is assumed
+to be a directory as well.  Best efforts are made to retain the
+properties of the original file in the output file.  Currently,
+.BR chpathtool " sets permissions, ownership and modification times.
+.P
+.BR chpathtool " is meant for the Prefix branch of Portage to relocate
+packages from one prefix offset to another.  This ability allows for the
+use of binary packages, even though built for a different prefix offset.
+.RB "When " chpathtool " has found a match inside a binary file, it replaces
+the string, and searches for the end of the string in the form of a
+zero-byte ('\\0').  At this byte, the neccessary padding bytes are
+inserted, such that the binary internally doesn't change in size.  This
+is important for binaries where offsets are used to find relevant pieces
+of data.  For certain files, this zero-byte is never found, such as in
+.RB "e.g. text files.  For those files, " chpathtool " will " not "
+write out the padding zero-bytes, and produce a warning about this
+instead.
+.P
+.RB "Because " chpathtool " attempts not to change the internal file
+.RI "structure, it can only operate if the length of " value " is not
+.RI "greater than the length of " magic ".
+.SH OPTIONS
+.TP
+.B -q
+Suppress messages about padding bytes which could not be written.
+.SH EXAMPLES
+.B chpathtool
+/var/tmp/my/old/prefix /var/tmp/new/prefix "/my/old/prefix" "/new/prefix"
+.SH "REPORTING BUGS"
+Please report bugs via http://bugs.gentoo.org/
+.SH AUTHORS
+Fabian Groffen <grobian@gentoo.org>