Man Linux: Main Page and Category List

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.

       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)