grep-dctrl, grep-status, grep-available, grep-aptavail - grep Debian control files

grep-dctrl [options] predicate [ file ... ] grep-status [options] predicate [ file ... ] grep-available [options] predicate [ file ... ] grep-aptavail [options] predicate [ file ... ] grep-dctrl --copying | --help | --version | -ChV grep-status --copying | --help | --version | -ChV grep-available --copying | --help | --version | -ChV grep-aptavail --copying | --help | --version | -ChV

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 predicate on the command line. The predicate defines which kind of paragraphs (aka package records) are output. An atomic predicate is a search pattern along with any options that modify it. Possible modifiers are --eregex, --field, --ignore-case, -P, --regex and --exact-match, along with their single-letter equivalents. An atomic predicate gives a pattern to search for. 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. Predicates can be combined using the connectives --and, --or and --not. Predicates can be grouped using parentheses.

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

There is one exception to the above: if the program name is grep-dctrl, the default input source is always standard input; this cannot be overridden by the configuration file.

The programs grep-available, grep-status and grep-aptavail are aliases of (actually, symbolic links to) grep-dctrl. In the shipped configuration, these aliases use as their default input the dpkg(8) available and status files and the apt-cache dumpavail output, respectively.

Atomic predicate modifiers

Predicate connectives

Output format modifiers

Miscellaneous

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

% grep-available -PX mixal

% 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

% grep-available -F Description -i foo

% grep-available -F Package foo

% grep-available -P foo

% grep-available -P -F Description foo

% grep-available -F Package -F Description foo

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

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'

% grep-available -F Maintainer -s Package,Depends \
  'ajk@debian.org'

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

% grep-dctrl -n -s Maintainer '' Sources | sort |
  uniq -c | sort -nr

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 -c -FMaintainer \
  "`grep-available -sMaintainer -n -PX grep-dctrl`"

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" | paste -sd "  \n" | sort -n             

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.

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 out of date.

a pattern is mandatory

You must specify a pattern to be searched for.

a predicate is required

No predicate 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 atom modifiers

Conflicting atom modifiers were used; for example, perhaps both -X and -e were specified for the same atom.

missing ')' in command line

There were more opening than closing parentheses in the given predicate.

no such log level

The argument to -l was invalid.

predicate is too complex

The predicate's complexity (the number of atoms and connectives) exceed compile-time limits.

read failure or out of memory

There was a problem reading the configuration file. Maybe there was a transput error; maybe memory was exhausted. This error may be transient, that is, if you try again, all may go well.

syntax error in command line

There is a problem in the command line. Look, and you shall find it.

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.

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.

unexpected end of file

The input file is broken: it ends before it should.

unexpected end of line

The input file is broken: a line ends before it should.

Unexpected atom in command line. Did you forget to use a connective?

There was an atom on the command line where there should not be any. The most likely reason is that an atom modifier option (such as -F) follows directly after a closing parenthesis. Adding a connective (--and, --or) between the parenthesis and the option is often the correct solution.

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.

/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. If the default input file name starts with two at (@) signs, one of them is ignored. This allows specifying a file name that starts with an at sign. If it starts with the string "@exec", the rest of the name is interpreted as a command name that is fed to /bin/sh -c, and the standard output stream is used as the default input.

/var/lib/dpkg/available

The default input file of grep-available when the shipped configuration is in effect.

/var/lib/dpkg/status

The default input file of grep-status when the shipped configuration is in effect.

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.

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

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