NAME¶
grep-dctrl, grep-status, grep-available, grep-aptavail, grep-debtags - grep
Debian control files
SYNOPSIS¶
command --copying|
-C |
--help|
-h |
--version|
-V
command [
options]
filter [
file... ]
where
command is one of
grep-dctrl,
grep-status,
grep-available,
grep-aptavail and
grep-debtags.
DESCRIPTION¶
The
grep-dctrl program can answer such questions as
What is the Debian
package foo?,
Which version of the Debian package bar is now
current?,
Which Debian packages does John Doe maintain?,
Which
Debian packages are somehow related to the Scheme programming
language?, and with some help,
Who maintain the essential packages of a
Debian system?, given a useful input file.
The programs
grep-available,
grep-status,
grep-aptavail and
grep-debtags are aliases of (actually, symbolic links to)
grep-dctrl. These aliases use as their default input the
dpkg(1)
available and
status files, the
apt-cache dumpavail
output and the
debtags dumpavail output, respectively.
grep-dctrl is a specialised
grep program that is meant for
processing any file which has the general format of a Debian package
control file, as described in the Debian Policy. These include the
dpkg available file, the
dpkg status file, and the
Packages files on a distribution medium (such as a Debian CD-ROM or an
FTP site carrying Debian).
You must give a
filter expression on the command line. The
filter
defines which kind of paragraphs (aka package records) are output. A simple
filter is a search pattern along with any options that modify it.
Possible modifiers are
--eregex,
--field,
--ignore-case,
--regex and
--exact-match, along with their single-letter
equivalents. By default, the search is a case-sensitive fixed substring match
on each paragraph (in other words, package record) in the input. With suitable
modifiers, this can be changed: the search can be case-insensitive and the
pattern can be seen as an extended POSIX regular expression.
Filters can be combined to form more complex
filters using the
connectives
--and,
--or and
--not. Parentheses (which
usually need to be escaped for the shell) can be used for grouping.
By default, the full matching paragraphs are printed on the standard output;
specific fields can be selected for output with the
-s option.
After the
filter expression comes zero or more
file names. The
file name
- is taken to mean the standard input stream. The
files are searched in order but separately; they are
not
concatenated together. In other words, the end of a
file always implies
the end of the current paragraph.
If no
file names are specified, the program name is used to identify a
default input file. The program names are matched with the base form of the
name of the current program (the 0'th command line argument, if you will).
OPTIONS¶
Specifying the search pattern¶
- --pattern=pattern
- Specify a pattern to be searched. This switch is not generally
needed, as the pattern can be given by itself. However,
patterns that start with a dash (-) must be given using this
switch, so that they wouldn't be mistaken for switches.
Modifiers of simple filters¶
- -F field,field, ... |
--field=field,field, ...
- Restrict pattern matching to the fields given. Multiple
field names in one -F option and multiple -F options
in one simple filter are allowed. The search named by the filter
will be performed among all the fields named, and as soon as any
one of them matches, the whole simple filter is considered
matching.
- A field specification can contain a colon (:). In such a
case, the part up to the colon is taken as the name of the field to be
searched in, and the part after the colon is taken as the name of the
field whose content is to be used if the field to search in is empty.
- -P
- Shorthand for -FPackage.
- -S
- Shorthand for -FSource:Package.
- -e, --eregex
- Regard the pattern of the current simple filter as an extended POSIX
regular expression
- -r, --regex
- Regard the pattern of the current simple filter as a standard POSIX
regular expression.
- -i, --ignore-case
- Ignore case when looking for a match in the current simple filter.
- -X, --exact-match
- Do an exact match (as opposed to a substring match) in the current simple
filter.
- -w, --whole-pkg
- Do an extended regular expression match on whole package names, assuming
the syntax of inter-package relationship fields such as
Depends,Recommends, ... When this flag is given you should
not worry about sub-package names such as "libpcre3" also
matching "libpcre3-dev". This flag implies (and is incompatible
with) -e.
- --eq
- Do an equality comparison under the Debian version number system. If the
pattern or the field to be searched in is not a valid Debian version
number, the paragraph is regarded as not matching. As a special case, this
is capable of comparing simple nonnegative integers for equality.
- --lt
- Do an strictly-less-than comparison under the Debian version number
system. If the pattern or the field to be searched in is not a valid
Debian version number, the paragraph is regarded as not matching. As a
special case, this is capable of comparing simple nonnegative
integers.
- --le
- Do an less-than-or-equal comparison under the Debian version number
system. If the pattern or the field to be searched in is not a valid
Debian version number, the paragraph is regarded as not matching. As a
special case, this is capable of comparing simple nonnegative
integers.
- --gt
- Do an strictly-greater-than comparison under the Debian version number
system. If the pattern or the field to be searched in is not a valid
Debian version number, the paragraph is regarded as not matching. As a
special case, this is capable of comparing simple nonnegative
integers.
- --ge
- Do an greater-than-or-equal comparison under the Debian version number
system. If the pattern or the field to be searched in is not a valid
Debian version number, the paragraph is regarded as not matching. As a
special case, this is capable of comparing simple nonnegative
integers.
Combining filters¶
- -!, --not, !
- Match if the following filter does not match.
- -o, --or
- Match if either one or both of the preceding and following filters
matches.
- -a, --and
- Match if both the preceding and the following filter match.
- ( ... )
- Parentheses can be used for grouping. Note that they need to be escaped
for most shells. Filter modifiers can be given before the opening
parentheses; they will be treated as if they had been repeated for each
simple filter inside the parentheses.
- -s field,field, ... |
--show-field=field, field, ...
- Show only the body of these fields from the matching paragraphs.
The field names must not include any colons or commas. Commas are
used to delimit field names in the argument to this option. The
fields are shown in the order given here. See also the option
-I. Note that in the absence of the --ensure--dctrl option,
if only one field is selected, no paragraph separator is output.
- -I, --invert-show
- Invert the meaning of option -s: show only the fields that have
not been named using a -s option. As an artefact of the
implementation, the order of the fields in the original paragraph is not
preserved.
A
field specification can contain a colon. In such a case, the part up to
the colon is taken as the name of the field to be shown, and the part after
the colon is taken as the name of the field whose content is to be used if the
field to be shown is empty.
- -d
- Show only the first line of the Description field from the matching
paragraphs. If no -s option is specified, this option also effects
-s Description; if there is a -s option but it does not
include the Description field name, one is appended to the option.
Thus the Description field's location in the output is determined
by the -s option, if any, the last field being the default.
- -n, --no-field-names
- Suppress field names when showing specified fields, only their bodies are
shown. Each field is printed in its original form without the field name,
the colon after it and any whitespace preceding the start of the
body.
- -v, --invert-match
- Instead of showing all the paragraphs that match, show those paragraphs
that do not match.
- -c, --count
- Instead of showing the paragraphs that match (or, with -v, that
don't match), show the count of those paragraphs.
- -q, --quiet, --silent
- Output nothing to the standard output stream. Instead, exit immediately
after finding the first match.
Miscellaneous¶
- --ensure-dctrl
- Ensure that the output is in dctrl format, specifically that there always
is an empty line separating paragraphs. This option is not honored if the
-n option has been selected, as that option deliberately requests a
non-dctrl format for the output. In a future version, this option may be
made the default behaviour.
- --compat
- Override any --ensure-dctrl option given earlier on the command
line.
- --ignore-parse-errors
- Ignore errors in parsing input. A paragraph which cannot be parsed is
ignored in its entirety, and the next paragraph is assumed to start after
the first newline since the location of the error.
- --debug-optparse
- Show how the current command line has been parsed.
- -l level, --errorlevel=level
- Set log level to level. level is one of fatal,
important, informational and debug, but the last may
not be available, depending on the compile-time options. These categories
are given here in order; every message that is emitted when fatal
is in effect, will be emitted in the important error level, and so
on. The default is important.
- -V, --version
- Print out version information.
- -C, --copying
- Print out the copyright license. This produces much output; be sure to
redirect or pipe it somewhere (such as your favourite pager).
- -h, --help
- Print out a help summary.
EXAMPLES¶
The almost simplest use of this program is to print out the status or available
record of a package. In this respect,
grep-dctrl is like
dpkg -s
or
dpkg --print-avail. To print out the status record of the package
"mixal", do
% grep-status -PX mixal
and to get its available record, use
% grep-available -PX mixal
In fact, you can ask for the record of the "mixal" package from any
Debian control file. Say, you have the Debian 6.0 CD-ROM's
Packages
file in the current directory; now you can do a
% grep-dctrl -PX mixal Packages
But
grep-dctrl can do more than just emulate
dpkg. It can
more-or-less emulate
apt-cache! That program has a search feature that
searches package descriptions. But we can do that too:
% grep-available -F Description foo
searches for the string "foo" case-sensitively in the descriptions of
all available packages. If you want case-insensitivity, use
% grep-available -F Description -i foo
Truth to be told,
apt-cache searches package names, too. We can
separately search in the names; to do so, do
% grep-available -F Package foo
or
% grep-available -P foo
which is pretty much the same thing. We can also search in both descriptions and
names; if match is found in either, the package record is printed:
% grep-available -P -F Description foo
or
% grep-available -F Package -F Description foo
This kind of search is the exactly same that
apt-cache does.
Here's one thing neither
dpkg nor
apt-cache do. Search for a
string in the whole
status or
available file (or any Debian
control file, for that matter) and print out all package records where we have
a match. Try
% grep-available dpkg
sometime and watch how thoroughly
dpkg has infiltrated Debian.
All the above queries were based on simple substring searches. But
grep-dctrl can handle regular expressions in the search pattern. For
example, to see the status records of all packages with either "apt"
or "dpkg" in their names, use
% grep-status -P -e 'apt|dpkg'
Now that we have seen all these fine and dandy queries, you might begin to
wonder whether it is necessary to always see the whole paragraph. You may be,
for example, interest only in the dependency information of the packages
involved. Fine. To show the depends lines of all packages maintained by me, do
a
% grep-available -F Maintainer -s Depends 'ajk@debian.org'
If you want to see the packages' names, too, use
% grep-available -F Maintainer -s Package,Depends \
'ajk@debian.org'
Note that there must be no spaces in the argument to the
-s switch.
More complex queries are also possible. For example, to see the list of packages
maintained by me and depending on libc6, do
% grep-available -F Maintainer 'ajk@debian.org' \
-a -F Depends libc6 -s Package,Depends
Remember that you can use other UNIX filters to help you, too. Ever wondered,
who's the most active Debian developer based on the number of source packages
being maintained? Easy. You just need to have a copy of the most recent
Sources file from any Debian mirror.
% grep-dctrl -n -s Maintainer '' Sources | sort | \
uniq -c | sort -nr
This example shows a neat trick: if you want to selectively show only some field
of
all packages, just supply an empty pattern.
The term "bogopackage" means the count of the packages that a Debian
developer maintains. To get the bogopackage count for the maintainer of
dctrl-tools, say
% grep-available -c -FMaintainer \
"`grep-available -sMaintainer -n -PX dctrl-tools`"
Sometimes it is useful to output the data of several fields on the same line.
For example, the following command outputs the list of installed packages,
sorted by their
Installed-Size.
% grep-status -FStatus -sInstalled-Size,Package -n \
"install ok installed" -a -FInstalled-Size --gt 0 \
| paste -sd " \n" | sort -n
Note that there should be exactly 2 spaces in the " \n" string.
Another usual use-case is looking for packages that have another one as build
dependency:
% grep-dctrl -s Package -F Build-Depends,Build-Depends-Indep \
quilt /var/lib/apt/lists/*Sources
These examples cover a lot of typical uses of this utility, but not all possible
uses. Use your imagination! The building blocks are there, and if something's
missing, let me know.
DIAGNOSTICS¶
In the absence of errors, the exit code
0 is used if at least one match
was found, and the exit code
1 is used if no matches were found. If
there were errors, the exit code is
2, with one exception. If the
-q,
--quiet or
--silent options are used, the exit code
0 is used when a match is found regardless of whether there have been
non-fatal errors.
These messages are emitted in log levels
fatal and
important.
Additional messages may be provided by the system libraries.
This list is
incomplete.
- A pattern is mandatory
- You must specify a pattern to be searched for.
- malformed filter
- No filter was specified, but one is required.
- cannot find enough memory
- More memory was needed than was available. This error may be transient,
that is, if you try again, all may go well.
- cannot suppress field names when showing whole paragraphs
- When you do not use the -s switch, grep-dctrl just passes
the matching paragraphs through, not touching them any way. This means,
for example, that you can only use -n when you use -s.
- inconsistent modifiers of simple filters
- Conflicting modifiers of simple filters were used; for example, perhaps
both -X and -e were specified for the same simple
filter.
- missing ')' in command line
- There were more opening than closing parentheses in the given filter.
- no such log level
- The argument to -l was invalid.
- too many file names
- The number of file names specified in the command line exceeded a
compile-time limit.
- too many output fields
- The argument to -s had too many field names in it. This number is
limited to 256.
- unexpected ')' in command line
- There was no opening parenthesis that would match some closing parenthesis
in the command line.
FILES¶
- /var/lib/dpkg/available
- The default input file of grep-available.
- /var/lib/dpkg/status
- The default input file of grep-status.
AUTHOR¶
The program and this manual page were written by Antti-Juhani Kaijanaho
<
gaia@iki.fi>. Bill Allombert <
ballombe@debian.org>
provided one of the examples in the manual page.
SEE ALSO¶
Debian Policy Manual. Published as the Debian package
debian-policy. Also
available in the Debian website.
apt-cache(1),
ara(1),
dpkg-awk(1),
sgrep(1),
dpkg(8)