grep-available man page on ElementaryOS

Man page or keyword search:  
man Server   4994 pages
apropos Keyword Search (all sections)
Output format
ElementaryOS logo
[printable version]

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
       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.  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
       -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.   Note  that	in  the absence of the --ensure--dctrl
	      option, 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
	      immediately 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
	      option  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 behaviour.

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

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

       -l level, --errorlevel=level
	      Set log 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  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 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
       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 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 -l 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			  2012-04-22			 GREP-DCTRL(1)
[top]

List of man pages available for ElementaryOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
...................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net