Manpages

Manpage of GREP-DCTRL

GREP-DCTRL

Section: Debian user's manual (1)
Updated: 2001-07-19
Index
Return to Main Contents
 

NAME

grep-dctrl - grep Debian control files  

SYNOPSIS

grep-dctrl [ options ] pattern [ file ... ]

grep-dctrl --copying | --help | --version | -ChV  

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.

It 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 Packaging Manual. 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 search pattern on the command line. By default, the search is a case-sensitive fixed substring match on each paragraph (in other words, package record) in the input. With suitable command-line options, this can be changed: the search can be case-insensitive and the pattern can be seen as an extended POSIX regular expression. By default, the full matching paragraphs are printed on the standard output; specific fields can be selected for output with the -s option. One can also restrict the search to the body of particular fields; see the -F option. You can also search for packages that don't match a certain criteria; see the -v option.

After the search pattern comes zero or more file names. If no file names are specified, the file name is searched in configuration files. The input file from the first program name - input file association with the correct program name is used. 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). 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.  

OPTIONS

-l LEVEL, --errorlevel=LEVEL
Set debugging 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".
-F FIELD,FIELD,...; --field=FIELD,FIELD,...
Restrict pattern matching to the FIELDs given. You can also specify several -F options.
-P
Shorthand for "-FPackage".
-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.
-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 predecing the start of the body.
-e, --eregex
Regard the pattern as an extended POSIX regular expression
-r, --regex
The pattern is a standard POSIX regular expression.
-i, --ignore-case
Ignore case when looking for a match.
-v, --invert-match
Instead of showing all the paragraphs that match, show those paragraphs that do not match.
--count
Instead of showing the paragraphs that match (or, with -v, that don't match), show the count of those paragraphs.
-c
This option is disabled as of grep-dctrl 1.6. It used to mean the same as "--config-file", but this will change in the future. In a future version of grep-dctrl, the "-c" option will become synonymous with the option "--count".
--config-file=FNAME
Use FNAME as the config file instead of the defaults.
-X, --exact-match
Do an exact match (as opposed to a substring match).
-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 following example queries assume that the default configuration is in effect.

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 2.2 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.

You can do more complex (conjunctive) queries by using the Unix pipeline as a helper tool. This is usually most useful when you want to narrow down queries based on different patterns and different fields. For example, to see the list of packages maintained by me and depending on libc6, do

% grep-available -F Maintainer -s Package,Depends \
  'ajk@debian.org' | grep-dctrl -F Depends -s Package libc6
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 grep-dctrl, say

% grep-available -FMaintainer --count \
  "`grep-available -PX -sMaintainer -n grep-dctrl`"

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

These messages are emitted in log levels "fatal" and "important".
you can only use -s once
You must give all fields to show in one -s command. Usually many -s's are typos anyway, so heed this message: remove one of the -s's or merge all of them into one -s.
no such log level
The argument to -l was invalid.
cumulative field name exceeds maximum length
The combined length of the argument to all -F options given may not exceed 512 bytes. Longer arguments cannot be used.
too many fields to search in
Too many fields were specified for searchin in. This number is limited to 256.
output field spec exceeds maximum length
The argument to -s was too long; it is restricted to 512 bytes. Longer arguments cannot be used.
too many output fields
The argument to -s had too many field names in it. This number is limited to 256.
do not use both -e and -r options
The pattern cannot be both a standard POSIX regular expression and an extended POSIX regular expression at the same time. You must use at most one of the options -e and -r; using both does not make sense.
I'm broken - please report this to <gaia@iki.fi>
An internal consistency check failed. Please, report this bug.
a pattern is mandatory
You must specify a pattern to be searched.
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.
don't know how to do an exact regex match
Currently you cannot do exact match searches with regular expressions.
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.
need a file name to grep
For some reason no file name is available. This means that the configuration file did not list a default file name for this name of the program, and no file name was given on the command line.
syntax error: need a executable name
There is a problem in the configuration file. Look, and you shall find it.
syntax error: need an input file name
There is a problem in the configuration file. Look, and you shall find it.
 

COMPATIBILITY

If you use grep-dctrl in a Debian package, you should depend on the grep-dctrl package and heed the following compatibility notes:

Always call only the grep-dctrl executable.
Although the grep-status and grep-available symlinks are installed by default, this may change in the future. Those symlinks are meant for manual and not scripted use.
Always specify an explicit file name
Don't rely on the implicit file name feature. The system administrator may have changed the default file name. You should always specify the "-" file, too.
Not all features have been with us in every version
Check if any of the features you use is mentioned in the changelog. Use a versioned dependency on grep-dctrl, if it is necessary.
 

FILES

/etc/grep-dctrl.rc
See the next file.
~/.grep-dctrlrc
These files are the default configuration files for grep-dctrl. The format is line-based, with `#' introducing a comment that lasts to the end of the line. Each line defines one association between a program name and a default input file. These two things are listed in the line in order, separated by whitespace. Empty lines are ignored.
 

AUTHOR

The program and this manual page were written by Antti-Juhani Kaijanaho <gaia@iki.fi>.  

SEE ALSO

Ian Jackson et al.: Debian Packaging Manual. Published as the Debian package packaging-manual. Also available in the Debian website. The Debian project, 1999.

apt-cache(1), dpkg(1), dpkg-awk(1), sgrep(1)


 

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
EXAMPLES
DIAGNOSTICS
COMPATIBILITY
FILES
AUTHOR
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 10:48:01 GMT, March 29, 2024