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