doc/apt-cache.8.sgml

   1 <!-- -*- mode: sgml; mode: fold -*- -->
   2 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [
   3
   4 <!ENTITY % aptent SYSTEM "apt.ent">
   5 %aptent;
   6
   7 ]>
   8
   9 <refentry>
  10  &apt-docinfo;
  11
  12  <refmeta>
  13    <refentrytitle>apt-cache</>
  14    <manvolnum>8</>
  15  </refmeta>
  16
  17  <!-- Man page title -->
  18  <refnamediv>
  19     <refname>apt-cache</>
  20     <refpurpose>APT package handling utility -- cache manipulator</>
  21  </refnamediv>
  22
  23  <!-- Arguments -->
  24  <refsynopsisdiv>
  25    <cmdsynopsis>
  26       <command>apt-cache</>
  27       <arg><option>-hvsn</></arg>
  28       <arg><option>-o=<replaceable/config string/</></arg>
  29       <arg><option>-c=<replaceable/file/</></arg>
  30       <group choice=req>
  31          <arg>add <arg choice="plain" rep="repeat"><replaceable>file</replaceable></arg></arg>
  32          <arg>gencaches</>
  33          <arg>showpkg <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
  34          <arg>showsrc <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
  35          <arg>stats</>
  36          <arg>dump</>
  37          <arg>dumpavail</>
  38          <arg>unmet</>
  39          <arg>search <arg choice="plain"><replaceable>regex</replaceable></arg></arg>
  40          <arg>show <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
  41          <arg>depends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
  42          <arg>rdepends <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
  43          <arg>pkgnames <arg choice="plain"><replaceable>prefix</replaceable></arg></arg>
  44          <arg>dotty <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
  45          <arg>policy <arg choice="plain" rep="repeat"><replaceable>pkgs</replaceable></arg></arg>
  46       </group>
  47    </cmdsynopsis>
  48  </refsynopsisdiv>
  49
  50  <RefSect1><Title>Description</>
  51    <para>
  52    <command/apt-cache/ performs a variety of operations on APT's package
  53    cache. <command/apt-cache/ does not manipulate the state of the system
  54    but does provide operations to search and generate interesting output
  55    from the package metadata.
  56
  57    <para>
  58    Unless the <option/-h/, or <option/--help/ option is given, one of the
  59    commands below must be present.
  60
  61    <VariableList>
  62      <VarListEntry><Term>add <replaceable/file(s)/</Term>
  63      <ListItem><Para>
  64      <literal/add/ adds the named package index files to the package cache.
  65      This is for debugging only.
  66      </VarListEntry>
  67
  68      <VarListEntry><Term>gencaches</Term>
  69      <ListItem><Para>
  70      <literal/gencaches/ performs the same operation as
  71      <command/apt-get check/. It builds the source and package caches from
  72      the sources in &sources-list; and from <filename>/var/lib/dpkg/status</>.
  73      </VarListEntry>
  74
  75      <VarListEntry><Term>showpkg <replaceable/pkg(s)/</Term>
  76      <ListItem><Para>
  77      <literal/showpkg/ displays information about the packages listed on the
  78      command line. Remaining arguments are package names. The available
  79      versions and reverse dependencies of each package listed are listed, as
  80      well as forward dependencies for each version. Forward (normal)
  81      dependencies are those packages upon which the package in question
  82      depends; reverse dependencies are those packages that depend upon the
  83      package in question. Thus, forward dependencies must be satisfied for a
  84      package, but reverse dependencies need not be.
  85      For instance, <command>apt-cache showpkg libreadline2</> would produce
  86      output similar to the following:
  87
  88 <informalexample><programlisting>
  89 Package: libreadline2
  90 Versions: 2.1-12(/var/state/apt/lists/foo_Packages),
  91 Reverse Depends:
  92   libreadlineg2,libreadline2
  93   libreadline2-altdev,libreadline2
  94 Dependencies:
  95 2.1-12 - libc5 (2 5.4.0-0) ncurses3.0 (0 (null))
  96 Provides:
  97 2.1-12 -
  98 Reverse Provides:
  99 </programlisting></informalexample>
 100
 101      <para>
 102      Thus it may be seen that libreadline2, version 2.1-12, depends on libc5 and
 103      ncurses3.0 which must be installed for libreadline2 to work.
 104      In turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If
 105      libreadline2 is installed, libc5 and ncurses3.0 (and ldso) must also be
 106      installed; libreadlineg2 and libreadline2-altdev do not have to be
 107      installed. For the specific meaning of the remainder of the output it
 108      is best to consult the apt source code.
 109      </VarListEntry>
 110
 111      <VarListEntry><Term>stats</Term>
 112      <ListItem><Para>
 113      <literal/stats/ displays some statistics about the cache.
 114      No further arguments are expected. Statistics reported are:
 115      <itemizedlist>
 116        <listitem><para>
 117        <literal/Total package names/ is the number of package names found
 118        in the cache.
 119        </listitem>
 120
 121        <listitem><para>
 122        <literal/Normal packages/ is the number of regular, ordinary package
 123        names; these are packages that bear a one-to-one correspondence between
 124        their names and the names used by other packages for them in
 125        dependencies. The majority of packages fall into this category.
 126        </listitem>
 127
 128        <listitem><para>
 129        <literal/Pure virtual packages/ is the number of packages that exist
 130        only as a virtual package name; that is, packages only "provide" the
 131        virtual package name, and no package actually uses the name. For
 132        instance, "mail-transport-agent" in the Debian GNU/Linux system is a
 133        pure virtual package; several packages provide "mail-transport-agent",
 134        but there is no package named "mail-transport-agent".
 135        </listitem>
 136
 137        <listitem><para>
 138        <literal/Single virtual packages/ is the number of packages with only
 139        one package providing a particular virtual package. For example, in the
 140        Debian GNU/Linux system, "X11-text-viewer" is a virtual package, but
 141        only one package, xless, provides "X11-text-viewer".
 142        </listitem>
 143
 144        <listitem><para>
 145        <literal/Mixed virtual packages/ is the number of packages that either
 146        provide a particular virtual package or have the virtual package name
 147        as the package name. For instance, in the Debian GNU/Linux system,
 148        "debconf" is both an actual package, and provided by the debconf-tiny
 149        package.
 150        </listitem>
 151
 152        <listitem><para>
 153        <literal/Missing/ is the number of package names that were referenced in
 154        a dependency but were not provided by any package. Missing packages may
 155        be in evidence if a full distribution is not accessed, or if a package
 156        (real or virtual) has been dropped from the distribution. Usually they
 157        are referenced from Conflicts statements.
 158        </listitem>
 159
 160        <listitem><para>
 161        <literal/Total distinct/ versions is the number of package versions
 162        found in the cache; this value is therefore at least equal to the
 163        number of total package names. If more than one distribution (both
 164        "stable" and "unstable", for instance), is being accessed, this value
 165        can be considerably larger than the number of total package names.
 166        </listitem>
 167
 168        <listitem><para>
 169        <literal/Total dependencies/ is the number of dependency relationships
 170        claimed by all of the packages in the cache.
 171        </listitem>
 172      </itemizedlist>
 173      </VarListEntry>
 174
 175      <VarListEntry><Term>showsrc <replaceable/pkg(s)/</Term>
 176      <ListItem><Para>
 177      <literal/showsrc/ displays all the source package records that match
 178      the given package names. All versions are shown, as well as all
 179      records that declare the name to be a Binary.
 180      </VarListEntry>
 181
 182      <VarListEntry><Term>dump</Term>
 183      <ListItem><Para>
 184      <literal/dump/ shows a short listing of every package in the cache. It is
 185      primarily for debugging.
 186      </VarListEntry>
 187
 188      <VarListEntry><Term>dumpavail</Term>
 189      <ListItem><Para>
 190      <literal/dumpavail/ prints out an available list to stdout. This is
 191      suitable for use with &dpkg; and is used by the &dselect; method.
 192      </VarListEntry>
 193
 194      <VarListEntry><Term>unmet</Term>
 195      <ListItem><Para>
 196      <literal/unmet/ displays a summary of all unmet dependencies in the
 197      package cache.
 198      </VarListEntry>
 199
 200      <VarListEntry><Term>show <replaceable/pkg(s)/</Term>
 201      <ListItem><Para>
 202      <literal/show/ performs a function similar to
 203      <command>dpkg --print-avail</>i; it displays the package records for the
 204      named packages.
 205      </VarListEntry>
 206
 207      <VarListEntry><Term>search <replaceable/regex [ regex ... ]/</Term>
 208      <ListItem><Para>
 209      <literal/search/ performs a full text search on all available package
 210      lists for the regex pattern given. It searches the package names and the
 211      descriptions for an occurrence of the regular expression and prints out
 212      the package name and the short description. If <option/--full/ is given
 213      then output identical to <literal/show/ is produced for each matched
 214      package, and if <option/--names-only/ is given then the long description
 215      is not searched, only the package name is.
 216      <para>
 217      Separate arguments can be used to specify multiple search patterns that
 218      are and'ed together.
 219      </VarListEntry>
 220
 221      <VarListEntry><Term>depends <replaceable/pkg(s)/</Term>
 222      <ListItem><Para>
 223      <literal/depends/ shows a listing of each dependency a package has
 224      and all the possible other packages that can fulfill that dependency.
 225      </VarListEntry>
 226
 227      <VarListEntry><Term>rdepends <replaceable/pkg(s)/</Term>
 228      <ListItem><Para>
 229      <literal/rdepends/ shows a listing of each reverse dependency a package
 230      has.
 231      </VarListEntry>
 232
 233      <VarListEntry><Term>pkgnames <replaceable/[ prefix ]/</Term>
 234      <ListItem><Para>
 235      This command prints the name of each package in the system. The optional
 236      argument is a prefix match to filter the name list. The output is suitable
 237      for use in a shell tab complete function and the output is generated
 238      extremely quickly. This command is best used with the
 239      <option/--generate/ option.
 240      </VarListEntry>
 241
 242      <VarListEntry><Term>dotty <replaceable/pkg(s)/</Term>
 243      <ListItem><Para>
 244      <literal/dotty/ takes a list of packages on the command line and
 245      generates output suitable for use by dotty from the
 246      <ulink url="http://www.research.att.com/sw/tools/graphviz/">GraphViz</>
 247      package. The result will be a set of nodes and edges representing the
 248      relationships between the packages. By default the given packages will
 249      trace out all dependent packages; this can produce a very large graph.
 250      To limit the output to only the packages listed on the command line,
 251      set the <literal>APT::Cache::GivenOnly</> option.
 252
 253      <para>
 254      The resulting nodes will have several shapes; normal packages are boxes,
 255      pure provides are triangles, mixed provides are diamonds,
 256      missing packages are hexagons. Orange boxes mean recursion was stopped
 257      [leaf packages], blue lines are pre-depends, green lines are conflicts.
 258
 259      <para>
 260      Caution, dotty cannot graph larger sets of packages.
 261
 262      <VarListEntry><Term>policy <replaceable/[ pkg(s) ]/</Term>
 263      <ListItem><Para>
 264      <literal/policy/ is ment to help debug issues relating to the
 265      preferences file. With no arguments it will print out the
 266      priorities of each source. Otherwise it prints out detailed information
 267      about the priority selection of the named package.
 268      </VarListEntry>
 269    </VariableList>
 270  </RefSect1>
 271
 272  <RefSect1><Title>Options</>
 273    &apt-cmdblurb;
 274
 275    <VariableList>
 276      <VarListEntry><term><option/-p/</><term><option/--pkg-cache/</>
 277      <ListItem><Para>
 278      Select the file to store the package cache. The package cache is the
 279      primary cache used by all operations.
 280      Configuration Item: <literal/Dir::Cache::pkgcache/.
 281      </VarListEntry>
 282
 283      <VarListEntry><term><option/-s/</><term><option/--src-cache/</>
 284      <ListItem><Para>
 285      Select the file to store the source cache. The source is used only by
 286      <literal/gencaches/ and it stores a parsed version of the package
 287      information from remote sources. When building the package cache the
 288      source cache is used to advoid reparsing all of the package files.
 289      Configuration Item: <literal/Dir::Cache::srcpkgcache/.
 290      </VarListEntry>
 291
 292      <VarListEntry><term><option/-q/</><term><option/--quiet/</>
 293      <ListItem><Para>
 294      Quiet; produces output suitable for logging, omitting progress indicators.
 295      More q's will produce more quietness up to a maximum of 2. You can also use
 296      <option/-q=#/ to set the quietness level, overriding the configuration file.
 297      Configuration Item: <literal/quiet/.
 298      </VarListEntry>
 299
 300      <VarListEntry><term><option/-i/</><term><option/--important/</>
 301      <ListItem><Para>
 302      Print only important dependencies; for use with unmet. Causes only Depends and
 303      Pre-Depends relations to be printed.
 304      Configuration Item: <literal/APT::Cache::Important/.
 305      </VarListEntry>
 306
 307      <VarListEntry><term><option/-f/</><term><option/--full/</>
 308      <ListItem><Para>
 309      Print full package records when searching.
 310      Configuration Item: <literal/APT::Cache::ShowFull/.
 311      </VarListEntry>
 312
 313      <VarListEntry><term><option/-a/</><term><option/--all-versions/</>
 314      <ListItem><Para>
 315      Print full records for all available versions. This is the
 316      default; to turn it off, use <option/--no-all-versions/.
 317      If <option/--no-all-versions/ is specified, only the candidate version
 318      will displayed (the one which would be selected for installation).
 319      This option is only applicable to  the <literal/show/ command.
 320      Configuration Item: <literal/APT::Cache::AllVersions/.
 321      </VarListEntry>
 322
 323      <VarListEntry><term><option/-g/</><term><option/--generate/</>
 324      <ListItem><Para>
 325      Perform automatic package cache regeneration, rather than use the cache
 326      as it is. This is the default; to turn it off, use <option/--no-generate/.
 327      Configuration Item: <literal/APT::Cache::Generate/.
 328      </VarListEntry>
 329
 330      <VarListEntry><term><option/--names-only/</><term><option/-n/</>
 331      <ListItem><Para>
 332      Only search on the package names, not the long descriptions.
 333      Configuration Item: <literal/APT::Cache::NamesOnly/.
 334      </VarListEntry>
 335
 336      <VarListEntry><term><option/--all-names/</>
 337      <ListItem><Para>
 338      Make <literal/pkgnames/ print all names, including virtual packages
 339      and missing dependencies.
 340      Configuration Item: <literal/APT::Cache::AllNames/.
 341      </VarListEntry>
 342
 343      <VarListEntry><term><option/--recurse/</>
 344      <ListItem><Para>
 345      Make <literal/depends/ recursive so that all packages mentioned are
 346      printed once.
 347      Configuration Item: <literal/APT::Cache::RecurseDepends/.
 348      </VarListEntry>
 349
 350      &apt-commonoptions;
 351
 352    </VariableList>
 353  </RefSect1>
 354
 355  <RefSect1><Title>Files</>
 356    <variablelist>
 357      <VarListEntry><term><filename>/etc/apt/sources.list</></term>
 358      <ListItem><Para>
 359      Locations to fetch packages from.
 360      Configuration Item: <literal/Dir::Etc::SourceList/.
 361      </VarListEntry>
 362
 363      <VarListEntry><term><filename>&statedir;/lists/</></term>
 364      <ListItem><Para>
 365      Storage area for state information for each package resource specified in
 366      &sources-list;
 367      Configuration Item: <literal/Dir::State::Lists/.
 368      </VarListEntry>
 369
 370      <VarListEntry><term><filename>&statedir;/lists/partial/</></term>
 371      <ListItem><Para>
 372      Storage area for state information in transit.
 373      Configuration Item: <literal/Dir::State::Lists/ (implicit partial).
 374      </VarListEntry>
 375    </variablelist>
 376  </RefSect1>
 377
 378  <RefSect1><Title>See Also</>
 379    <para>
 380    &apt-conf;, &sources-list;, &apt-get;
 381  </RefSect1>
 382
 383  <RefSect1><Title>Diagnostics</>
 384    <para>
 385    <command/apt-cache/ returns zero on normal operation, decimal 100 on error.
 386  </RefSect1>
 387
 388  &manbugs;
 389  &manauthor;
 390
 391 </refentry>