grep-dctrl

GREP-DCTRL(1)                Debian user's manual                GREP-DCTRL(1)

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-deb-
       tags  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  de-
       fines  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  de-
       fault,  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  connec-
       tives --and, --or and --not.  Parentheses (which usually need to be es-
       caped 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 per-
              formed 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 fil-
              ter.

       -X, --exact-match
              Do an exact match (as opposed to a substring match) in the  cur-
              rent 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 sys-
              tem.  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  sim-
              ple 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 fil-
              ters 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.

   Output format modifiers
       -l, --files-with-matches
              Output only the file names, each on its own line, of those files
              that contain at least one matching paragraph.  This is incompat-
              ible  with  the  -v  and -L options, and all other output format
              modifiers will be ignored.

       -L, --files-without-matches
              Output only the file names, each on its own line, of those files
              that do not contain any matching paragraphs.  This is incompati-
              ble with the -v and -l options, and all other output format mod-
              ifiers will be ignored.

       -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  op-
              tion  -I.   Note  that in the absence of the --ensure--dctrl op-
              tion, 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  imple-
              mentation,  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 im-
              mediately 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  op-
              tion  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 behav-
              iour.

       --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 as-
              sumed to start after the first newline since the location of the
              error.

       --debug-optparse
              Show how the current command line has been parsed.

       --errorlevel=level
              Set log level to level.  level is one of fatal,  important,  in-
              formational  and  debug,  but the last may not be available, de-
              pending 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 De-
       bian 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 sepa-
       rately 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  de-
       scriptions  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 pack-
       ages 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.   Addi-
       tional  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  fil-
              ter.

       missing ')' in command line
              There  were  more  opening than closing parentheses in the given
              filter.

       no such log level
              The argument to --errorlevel 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)

Debian Project                    2013-11-26                     GREP-DCTRL(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2024 Hurricane Electric. All Rights Reserved.