Provided by: dctrl-tools_2.18ubuntu1_amd64 bug

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] predicate [ 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.  In the shipped configuration, these aliases use
       as  their  default  input  the dpkg(8) 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 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 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.   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.

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
              The pattern of the current simple filter is 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.

   Output format modifiers
       -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.

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

       --config-file=FNAME
              Use FNAME as the config file instead of the defaults.

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

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

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

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

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.

              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.

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

       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)