grep-available

       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-deb-
       tags  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 dis-
       tribution 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 connec-
       tives --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
              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 con-
       tent 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  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.

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

   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 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
              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", "impor-
              tant", "informational" and "debug", but  the  last  may  not  be
              available,  depending  on the compile-time options.  These cate-
              gories 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
       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 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.

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

       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 sym-
              links 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 admin-
              istrator 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 con-
              figuration is in effect.

       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)







Debian Project                    2007-10-27                     GREP-DCTRL(1)
Man Pages Copyright Respective Owners. Site Copyright (C) 1994 - 2017 Hurricane Electric. All Rights Reserved.