- qfile -f file support. TGL bug #158829

5 files changed, 142 insertions, 36 deletions

diff --git a/man/include/qfile-02-orphans.include b/man/include/qfile-02-orphans.include
index 3692524..0b7d463 100644
--- a/man/include/qfile-02-orphans.include
+++ b/man/include/qfile-02-orphans.include
@@ -22,20 +22,3 @@ any package:
 	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
diff --git a/man/include/qfile-04-from.include b/man/include/qfile-04-from.include
new file mode 100644
index 0000000..47c20d4
--- /dev/null
+++ b/man/include/qfile-04-from.include
@@ -0,0 +1,61 @@
+[Reading arguments from a file (or stdin)]
+.PP
+When you try to launch \fBqfile\fP with a large number of arguments, you may
+hit the following shell error:
+.nf\fI
+	$ qfile -o $(find /usr/lib)
+	bash: ./qfile: Argument list too long
+.fi
+.PP
+To avoid that, you must use the \fB\-\-from\fP (\fB\-f\fP) option, which
+allows reading your arguments list in a file:
+.nf\fI
+	$ find /usr/lib > ~/usr-lib.list
+	$ qfile -o -f ~/usr-lib.list
+	/usr/lib/libMagick-5.5.7-Q16.so.0.0.0
+	/usr/lib/libGL.so
+	...
+.fi
+.PP
+Your arguments list must be formatted with one file per line, and without any
+kind of garbage (no leading or trailing space, no empty line, etc.).  The 
+default \fBfind\fP output format is just fine in general.
+.PP
+You can also read the arguments list from standard input with the "\fB\-\fP" 
+pseudo filename, which is useful with shell pipes:
+.nf\fI
+	$ find /usr/lib | qfile -o -f -
+	/usr/lib/libMagick-5.5.7-Q16.so.0.0.0
+	/usr/lib/libGL.so
+	...
+.fi
+.PP
+Here is an other example of use.  This script lists some files which may be
+orphan config files left behind by Portage after uninstallation or upgrade of 
+some packages:
+.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} | qfile -o -f -
+.fi
+.PP
+\fBIMPORTANT:\fP this script is just a quick example.  Do not blindly delete the
+files it will list!
+.PP
+When reading arguments from a file or from stdin, \fBqfile\fP will, for
+performances reasons, treat then by groups of 5000 (search owners of the
+5000 first files, then of the 5000 following ones, etc.).  This magic value
+should be fine in most cases, but you can change it if you really want, using
+the \fB\-\-max\-args\fP option (\fB\-m\fP).  Using a greater value will eat a
+bit more memory, but may be a bit faster for really big queries.  Be careful
+though, using some stupidly high or low value can completly kill the
+performances.  In short, you probably don't want to touch this option.
+.PP
diff --git a/man/include/qfile-99-authors.include b/man/include/qfile-99-authors.include
new file mode 100644
index 0000000..1daf476
--- /dev/null
+++ b/man/include/qfile-99-authors.include
@@ -0,0 +1,4 @@
+[Additional Contributors]
+.TP
+TGL degrenier[at]easyconnect.fr
+.TP
diff --git a/man/mkman.sh b/man/mkman.sh
index e4a30bd..4600bf0 100755
--- a/man/mkman.sh
+++ b/man/mkman.sh
@@ -12,6 +12,7 @@ for applet in $APPLETS; do
 	sed  -i -e s/'PORTAGE-UTILS-CVS:'/${applet}/g \
 		-e s/'portage-utils-cvs:'/${applet}/g \
 		-e '/\.SH SYNOPSIS/,/\.SH/'s/' : .*\\fR$'/'\\fR'/ \
+		-e '/\.SH DESCRIPTION/,/\.SH/s|^\(Options:.*\)\\fR\(.*\)|\1\2\\fR|' \
 		-e s/'> \*'/'>@\.BR@ \*'/g ${applet}.1
 	head -n $(($(cat ${applet}.1 | wc -l)-1)) ${applet}.1 \
 		| tr '@' '\n' > ${applet}.1~ && mv ${applet}.1~ ${applet}.1
diff --git a/man/qfile.1 b/man/qfile.1
index 9509876..83c4230 100644
--- a/man/qfile.1
+++ b/man/qfile.1
@@ -5,11 +5,20 @@ qfile \- list all pkgs owning files
 .B qfile
 \fI<filename>\fR
 .SH DESCRIPTION
-Options: \fB\-[eoRvqChV]\fR
+Options: \fB\-[ef:m:oRx:vqChV]\fR
 .TP
 \fB\-e\fR, \fB\-\-exact\fR
 * Exact match
 .TP
+\fB\-f\fR, \fB\-\-from\fR
+<arg>
+.BR
+ * Read arguments from file <arg> ("-" for stdin)
+.HP
+\fB\-m\fR, \fB\-\-max\-args\fR <arg>
+.BR
+ * Treat from file arguments by groups of <arg> (defaults to 5000)
+.TP
 \fB\-o\fR, \fB\-\-orphans\fR
 * List orphan files
 .TP
@@ -31,7 +40,7 @@ Options: \fB\-[eoRvqChV]\fR
 \fB\-V\fR, \fB\-\-version\fR
 * Print version and exit
 .PP
-$Id: qfile.1,v 1.20 2007/01/07 00:40:50 solar Exp $
+$Id: qfile.1,v 1.21 2007/01/07 18:30:03 solar Exp $
 file written for Gentoo by <solar and vapier 
  gentoo.org>
 .SH "FINDING FILES OWNERS"
@@ -99,23 +108,6 @@ any package:
 	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
@@ -155,3 +147,68 @@ Sure, the same differences hold when querying for orphan files:
 	/bin/dostuff.sh
 	$ ROOT=/mnt qfile -Ro /mnt/bin/*
 	/mnt/bin/dostuff.sh
+.fi
+.SH "READING ARGUMENTS FROM A FILE (OR STDIN)"
+.PP
+When you try to launch \fBqfile\fP with a large number of arguments, you may
+hit the following shell error:
+.nf\fI
+	$ qfile -o $(find /usr/lib)
+	bash: ./qfile: Argument list too long
+.fi
+.PP
+To avoid that, you must use the \fB\-\-from\fP (\fB\-f\fP) option, which
+allows reading your arguments list in a file:
+.nf\fI
+	$ find /usr/lib > ~/usr-lib.list
+	$ qfile -o -f ~/usr-lib.list
+	/usr/lib/libMagick-5.5.7-Q16.so.0.0.0
+	/usr/lib/libGL.so
+	...
+.fi
+.PP
+Your arguments list must be formatted with one file per line, and without any
+kind of garbage (no leading or trailing space, no empty line, etc.).  The 
+default \fBfind\fP output format is just fine in general.
+.PP
+You can also read the arguments list from standard input with the "\fB\-\fP" 
+pseudo filename, which is useful with shell pipes:
+.nf\fI
+	$ find /usr/lib | qfile -o -f -
+	/usr/lib/libMagick-5.5.7-Q16.so.0.0.0
+	/usr/lib/libGL.so
+	...
+.fi
+.PP
+Here is an other example of use.  This script lists some files which may be
+orphan config files left behind by Portage after uninstallation or upgrade of 
+some packages:
+.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} | qfile -o -f -
+.fi
+.PP
+\fBIMPORTANT:\fP this script is just a quick example.  Do not blindly delete the
+files it will list!
+.PP
+When reading arguments from a file or from stdin, \fBqfile\fP will, for
+performances reasons, treat then by groups of 5000 (search owners of the
+5000 first files, then of the 5000 following ones, etc.).  This magic value
+should be fine in most cases, but you can change it if you really want, using
+the \fB\-\-max\-args\fP option (\fB\-m\fP).  Using a greater value will eat a
+bit more memory, but may be a bit faster for really big queries.  Be careful
+though, using some stupidly high or low value can completly kill the
+performances.  In short, you probably don't want to touch this option.
+.PP
+.SH "ADDITIONAL CONTRIBUTORS"
+.TP
+TGL degrenier[at]easyconnect.fr