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