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