[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

[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

[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

.fi