- updated qfile ROOT and manpage handling.. TGL bug #142217

1 files changed, 130 insertions, 4 deletions

diff --git a/man/qfile.1 b/man/qfile.1
index d8bf53a..38a4326 100644
--- a/man/qfile.1
+++ b/man/qfile.1
@@ -1,18 +1,21 @@
 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.33.
-.TH qfile "1" "May 2006" "Gentoo Foundation" "qfile"
+.TH qfile "1" "August 2006" "Gentoo Foundation" "qfile"
 .SH NAME
 qfile \- manual page for qfile 
 .SH SYNOPSIS
 .B qfile
 \fI<filename> : list all pkgs owning files\fR
 .SH DESCRIPTION
-Options: \fB\-[evqChV]\fR
+Options: \fB\-[eoRvqChV]\fR
 .TP
 \fB\-e\fR, \fB\-\-exact\fR
 * Exact match
 .TP
 \fB\-o\fR, \fB\-\-orphans\fR
-* List orphans files (inverse matching)
+* List orphan files
+.TP
+\fB\-R\fR, \fB\-\-root\-prefix\fR
+* Assume arguments are already prefixed by $ROOT
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 * Make a lot of noise
@@ -29,4 +32,127 @@ Options: \fB\-[evqChV]\fR
 \fB\-V\fR, \fB\-\-version\fR
 * Print version and exit
 .PP
-$Id: qfile.1,v 1.17 2006/07/22 21:42:20 solar Exp $
+$Id: qfile.1,v 1.18 2006/08/21 00:11:54 solar Exp $
+file written for Gentoo by <solar and vapier 
+ gentoo.org>
+.SH "FINDING FILES OWNERS"
+.PP
+This is the default behavior of \fBqfile\fP.  It will list the packages which
+own the files (or directories, or symlinks, or anything else Portage can 
+install) you are querying.  Query items may be file paths or simple file names.
+By default, output includes packages names and the complete paths to
+the matching files.  If using \fB\-\-exact\fP, versions of the packages will 
+also be shown.  At the contrary, when using \fB\-\-quiet\fP, only package 
+names are listed, without files paths.  Finally, \fB\-\-verbose\fP is similar
+to \fB\-\-exact\fP, but may adds a few warnings.  The return status of 
+\fBqfile\fP will be \fI0\fP as soon as an owning package has been found for 
+one of the query items.
+.PP
+Find names of package(s) owning "/bin/bash":
+.nf\fI
+	$ qfile -q /bin/bash
+	app-shells/bash
+.fi
+.PP
+Find package(s) owning any file named "bash", and show paths of this files:
+.nf\fI
+	$ qfile bash
+	app-shells/bash (/bin/bash)
+	app-shells/bash (/etc/bash)
+.fi
+.PP
+Find packages(s) owning the file named "bash" in the current directory. Also 
+display their exact version:
+.nf\fI
+	$ cd /bin
+	$ qfile -e ./bash
+	app-shells/bash-3.1_p17 (/bin/bash)
+.fi
+.PP
+Find the package(s) owning the libraries needed by the Bash binary:
+.nf\fI
+	$ qfile $(scanelf -nq -F%n#F /bin/bash | tr , '\\n')
+	sys-libs/ncurses (/lib/libncurses.so.5)
+	sys-libs/glibc (/lib/libdl.so.2)
+	sys-libs/glibc (/lib/libc.so.6)
+.fi
+.SH "FINDING ORPHAN FILES"
+.PP
+\fBqfile\fP can also, with the \fB\-\-orphans\fP option, find files which are 
+not owned by any package.  This behavior is the opposite of the usual file 
+owner search: the output is the list of query items for which no reference has
+been found in your installed packages database.  The \fB\-\-exact\fP option has
+no effect in this mode, whereas \fB\-\-verbose\fP may add a few warning 
+messages.  As for \fB\-\-quiet\fP, it will completly turn off the output, 
+leaving just a silent test command, which returns \fI0\fP if and only if
+there was no orphan in your query items.
+.PP
+Find the orphan libtool files of your system:
+.nf\fI
+	$ qfile -o $(find /lib /usr/lib -name "*.la")
+	/usr/lib/libGL.la
+.fi
+.PP
+Find the libraries needed by the binary "foo" which have not been installed by
+any package:
+.nf\fI
+	$ qfile -o $(scanelf -nq -F%n#F /path/to/foo | tr , '\\n')
+	libinstalledmanually.so.2
+.fi
+.PP
+Script to find the orphan config files on your system 
+(\fBIMPORTANT:\fP this script is just a quick example.  Do not blindly delete
+the files it will list!):
+.nf\fI
+	#!/bin/bash
+	SEARCH_PATHS="$(portageq envvar CONFIG_PROTECT)"
+	SEARCH_MASK="$(portageq envvar CONFIG_PROTECT_MASK) \\
+		/etc/runlevels /etc/portage \\
+		/etc/ssl/certs /etc/ssh \\
+		/etc/bash_completion.d /etc/cups"
+	for path in ${SEARCH_MASK} ; do
+		EXCLUDE="${EXCLUDE} -not -path ${path}/*"
+	done
+	set -f
+	find ${SEARCH_PATHS} ${EXCLUDE} -print0 \\
+		| xargs -0 -n 500 qfile -o
+.fi
+.SH "HANDLING OF THE ROOT VARIABLE"
+.PP
+By setting the \fIROOT\fP environment variable, you can force \fBqfile\fP to
+work in the sytem of your choice. This example shows queries for owner of 
+"/bin/sh", first on your main system, and then on a system mounted on "/mnt":
+.nf\fI
+	$ qfile -q /bin/sh
+	app-shells/bash
+	$ ROOT=/mnt qfile -q /bin/sh
+	sys-apps/busybox
+.fi
+.PP
+Note that the query item is "/bin/sh" in both commands: by default, what 
+\fBqfile\fP looks for is file paths as they are recorded in the packages 
+database of the target system, and this paths don't include \fI$ROOT\fP.
+If, at the contrary, you want to query files with their current actual 
+paths (including the mount point), you should add the \fB\-\-root\-prefix\fP 
+(\fB\-R\fP) option:
+.nf\fI
+	$ ROOT=/mnt qfile -Rq /mnt/bin/sh
+	sys-apps/busybox
+.fi
+.PP
+The other difference beetween defaults and \fB\-R\fP queries is the output 
+of files paths.  The former doesn't include the \fI$ROOT\fP prefix, and the 
+later does:
+.nf\fI
+	$ ROOT=/mnt qfile sh
+	sys-apps/busybox (/bin/sh)
+	$ ROOT=/mnt qfile -R sh
+	sys-apps/busybox (/mnt/bin/sh)
+.fi
+.PP
+Sure, the same differences hold when querying for orphan files:
+.nf\fI
+	$ ROOT=/mnt qfile -o $(ls /mnt/bin/ | sed 's:^/mnt::')
+	/bin/dostuff.sh
+	$ ROOT=/mnt qfile -Ro /mnt/bin/*
+	/mnt/bin/dostuff.sh