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>-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>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>showpkg <arg choice="plain" rep="repeat"><replaceable>pkg</replaceable></arg></arg>
  42          <arg>depends <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</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 opration 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</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, 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 accesssed, 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</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      named packages.
 181      </VarListEntry>
 182
 183      <VarListEntry><Term>dump</Term>
 184      <ListItem><Para>
 185      <literal/dump/ shows a short listing of every package in the cache. It is
 186      primarily for debugging.
 187      </VarListEntry>
 188
 189      <VarListEntry><Term>dumpavail</Term>
 190      <ListItem><Para>
 191      <literal/dumpavail/ prints out an available list to stdout. This is
 192      suitable for use with &dpkg; and is used by the &dselect; method.
 193      </VarListEntry>
 194
 195      <VarListEntry><Term>unmet</Term>
 196      <ListItem><Para>
 197      <literal/unmet/ displays a summary of all unmet dependencies in the
 198      package cache.
 199      </VarListEntry>
 200
 201      <VarListEntry><Term>show</Term>
 202      <ListItem><Para>
 203      <literal/show/ performs a function similar to
 204      <command>dpkg --print-avail</>, it displays the package records for the
 205      named packages.
 206      </VarListEntry>
 207
 208      <VarListEntry><Term>search</Term>
 209      <ListItem><Para>
 210      <literal/search/ performs a full text search on all available package
 211      files for the regex pattern given. It searchs the package names and the
 212      descriptions for an occurance of the string and prints out the package
 213      name and the short description. If <option/--full/ is given then output
 214      identical to <literal/show/ is produced for each matched package and
 215      if <option/--names-only/ is given then the long description is not
 216      searched, only the package name is.
 217      <para>
 218      Seperate arguments can be used to specified multiple search patterns that
 219      are and'd together.
 220      </VarListEntry>
 221
 222      <VarListEntry><Term>depends</Term>
 223      <ListItem><Para>
 224      <literal/depends/ shows a listing of each dependency a package has
 225      and all the possible other packages that can fullfill that dependency.
 226      </VarListEntry>
 227
 228      <VarListEntry><Term>pkgnames</Term>
 229      <ListItem><Para>
 230      This command prints the name of each package in the system. The optional
 231      argument is a prefix match to filter the name list. The output is suitable
 232      for use in a shell tab complete function and the output is generated
 233      extremly quickly. This command is best used with the
 234      <option/--generate/ option.
 235      </VarListEntry>
 236
 237      <VarListEntry><Term>dotty</Term>
 238      <ListItem><Para>
 239      <literal/dotty/ takes a list of packages on the command line and
 240      gernerates output suitable for use by dotty from the
 241      <ulink url="http://www.research.att.com/sw/tools/graphviz/">GraphVis</>
 242      package. The result will be a set of nodes and edges representing the
 243      relationships between the packages. By default the given packages will
 244      trace out all dependent packages which can produce a very large graph.
 245      This can be turned off by setting the
 246      <literal>APT::Cache::GivenOnly</> option.
 247
 248      <para>
 249      The resulting nodes will have several shapse, normal packages are boxes,
 250      pure provides are triangles, mixed provides are diamonds,
 251      hexagons are missing packages. Orange boxes mean recursion was stopped
 252      [leaf packages], blue lines are prre-depends, green lines are conflicts.
 253
 254      <para>
 255      Caution, dotty cannot graph larger sets of packages.
 256
 257      <VarListEntry><Term>policy</Term>
 258      <ListItem><Para>
 259      <literal/policy/ is ment to help debug issues relating to the
 260      preferences file. With no arguments it will print out the
 261      priorities of each source. Otherwise it prints out detailed information
 262      about the priority selection of the named package.
 263      </VarListEntry>
 264    </VariableList>
 265  </RefSect1>
 266
 267  <RefSect1><Title>Options</>
 268    &apt-cmdblurb;
 269
 270    <VariableList>
 271      <VarListEntry><term><option/-p/</><term><option/--pkg-cache/</>
 272      <ListItem><Para>
 273      Select the file to store the package cache. The package cache is the
 274      primary cache used by all operations.
 275      Configuration Item: <literal/Dir::Cache::pkgcache/.
 276      </VarListEntry>
 277
 278      <VarListEntry><term><option/-s/</><term><option/--src-cache/</>
 279      <ListItem><Para>
 280      Select the file to store the source cache. The source is used only by
 281      <literal/gencaches/ and it stores a parsed version of the package
 282      information from remote sources. When building the package cache the
 283      source cache is used to advoid reparsing all of the package files.
 284      Configuration Item: <literal/Dir::Cache::srcpkgcache/.
 285      </VarListEntry>
 286
 287      <VarListEntry><term><option/-q/</><term><option/--quiet/</>
 288      <ListItem><Para>
 289      Quiet; produces output suitable for logging, omitting progress indicators.
 290      More qs will produce more quite up to a maximum of 2. You can also use
 291      <option/-q=#/ to set the quiet level, overriding the configuration file.
 292      Configuration Item: <literal/quiet/.
 293      </VarListEntry>
 294
 295      <VarListEntry><term><option/-i/</><term><option/--important/</>
 296      <ListItem><Para>
 297      Print only important deps; for use with unmet causes only Depends and
 298      Pre-Depends relations to be printed.
 299      Configuration Item: <literal/APT::Cache::Important/.
 300      </VarListEntry>
 301
 302      <VarListEntry><term><option/-f/</><term><option/--full/</>
 303      <ListItem><Para>
 304      Print full package records when searching.
 305      Configuration Item: <literal/APT::Cache::ShowFull/.
 306      </VarListEntry>
 307
 308      <VarListEntry><term><option/-a/</><term><option/--all-versions/</>
 309      <ListItem><Para>
 310      Print full records for all available versions, this is only applicable to
 311      the show command.
 312      Configuration Item: <literal/APT::Cache::AllVersions/.
 313      </VarListEntry>
 314
 315      <VarListEntry><term><option/-g/</><term><option/--generate/</>
 316      <ListItem><Para>
 317      Perform automatic package cache regeneration, rather than use the cache
 318      as it is. This is the default, to turn it off use <option/--no-generate/.
 319      Configuration Item: <literal/APT::Cache::Generate/.
 320      </VarListEntry>
 321
 322      <VarListEntry><term><option/--names-only/</>
 323      <ListItem><Para>
 324      Only search on the package names, not the long description.
 325      Configuration Item: <literal/APT::Cache::NamesOnly/.
 326      </VarListEntry>
 327
 328      <VarListEntry><term><option/--all-names/</>
 329      <ListItem><Para>
 330      Make <literal/pkgnames/ print all names, including virtual packages
 331      and missing dependencies.
 332      Configuration Item: <literal/APT::Cache::AllNames/.
 333      </VarListEntry>
 334
 335      <VarListEntry><term><option/--recurse/</>
 336      <ListItem><Para>
 337      Make <literal/depends/ recursive so that all packages mentioned are
 338      printed once.
 339      Configuration Item: <literal/APT::Cache::RecurseDepends/.
 340      </VarListEntry>
 341
 342      &apt-commonoptions;
 343
 344    </VariableList>
 345  </RefSect1>
 346
 347  <RefSect1><Title>Files</>
 348    <variablelist>
 349      <VarListEntry><term><filename>/etc/apt/sources.list</></term>
 350      <ListItem><Para>
 351      locations to fetch packages from.
 352      Configuration Item: <literal/Dir::Etc::SourceList/.
 353      </VarListEntry>
 354
 355      <VarListEntry><term><filename>&statedir;/lists/</></term>
 356      <ListItem><Para>
 357      storage area for state information for each package resource specified in
 358      &sources-list;
 359      Configuration Item: <literal/Dir::State::Lists/.
 360      </VarListEntry>
 361
 362      <VarListEntry><term><filename>&statedir;/lists/partial/</></term>
 363      <ListItem><Para>
 364      storage area for state information in transit.
 365      Configuration Item: <literal/Dir::State::Lists/ (implicit partial).
 366      </VarListEntry>
 367    </variablelist>
 368  </RefSect1>
 369
 370  <RefSect1><Title>See Also</>
 371    <para>
 372    &apt-conf;, &sources-list;, &apt-get;
 373  </RefSect1>
 374
 375  <RefSect1><Title>Diagnostics</>
 376    <para>
 377    <command/apt-cache/ returns zero on normal operation, decimal 100 on error.
 378  </RefSect1>
 379
 380  &manbugs;
 381  &manauthor;
 382
 383 </refentry>