* doc/*.xml:
[ntk/apt.git] / doc / apt-cache.8.xml
CommitLineData
24f6490f
AL
1<?xml version="1.0" encoding="utf-8" standalone="no"?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4
5<!ENTITY % aptent SYSTEM "apt.ent">
6%aptent;
7
0c1a7101
DK
8<!ENTITY % aptverbatiment SYSTEM "apt-verbatim.ent">
9%aptverbatiment;
10
24f6490f
AL
11]>
12
13<refentry>
5e80de29
AL
14
15 <refentryinfo>
16 &apt-author.jgunthorpe;
17 &apt-author.team;
18 &apt-email;
19 &apt-product;
20 <!-- The last update date -->
7fefa184 21 <date>04 February 2011</date>
5e80de29 22 </refentryinfo>
24f6490f
AL
23
24 <refmeta>
25 <refentrytitle>apt-cache</refentrytitle>
26 <manvolnum>8</manvolnum>
f0599b9c 27 <refmiscinfo class="manual">APT</refmiscinfo>
24f6490f
AL
28 </refmeta>
29
30 <!-- Man page title -->
31 <refnamediv>
32 <refname>apt-cache</refname>
7fefa184 33 <refpurpose>query the APT cache</refpurpose>
24f6490f
AL
34 </refnamediv>
35
6e8b4572
DK
36 &synopsis-command-apt-cache;
37
24f6490f
AL
38 <refsect1><title>Description</title>
39 <para><command>apt-cache</command> performs a variety of operations on APT's package
40 cache. <command>apt-cache</command> does not manipulate the state of the system
41 but does provide operations to search and generate interesting output
42 from the package metadata.</para>
43
44 <para>Unless the <option>-h</option>, or <option>--help</option> option is given, one of the
45 commands below must be present.</para>
46
47 <variablelist>
24f6490f 48 <varlistentry><term>gencaches</term>
c086ac18
DK
49 <listitem><para><literal>gencaches</literal> creates APT's package cache. This is done
50 implicitly by all commands needing this cache if it is missing or outdated.</para></listitem>
24f6490f
AL
51 </varlistentry>
52
c086ac18 53 <varlistentry><term>showpkg <replaceable>&synopsis-pkg;</replaceable>…</term>
24f6490f
AL
54 <listitem><para><literal>showpkg</literal> displays information about the packages listed on the
55 command line. Remaining arguments are package names. The available
56 versions and reverse dependencies of each package listed are listed, as
57 well as forward dependencies for each version. Forward (normal)
58 dependencies are those packages upon which the package in question
59 depends; reverse dependencies are those packages that depend upon the
60 package in question. Thus, forward dependencies must be satisfied for a
61 package, but reverse dependencies need not be.
62 For instance, <command>apt-cache showpkg libreadline2</command> would produce
63 output similar to the following:</para>
64
65<informalexample><programlisting>
66Package: libreadline2
67Versions: 2.1-12(/var/state/apt/lists/foo_Packages),
68Reverse Depends:
69 libreadlineg2,libreadline2
70 libreadline2-altdev,libreadline2
71Dependencies:
722.1-12 - libc5 (2 5.4.0-0) ncurses3.0 (0 (null))
73Provides:
742.1-12 -
75Reverse Provides:
76</programlisting></informalexample>
77
78 <para>Thus it may be seen that libreadline2, version 2.1-12, depends on
79 libc5 and ncurses3.0 which must be installed for libreadline2 to work.
80 In turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If
81 libreadline2 is installed, libc5 and ncurses3.0 (and ldso) must also be
82 installed; libreadlineg2 and libreadline2-altdev do not have to be
83 installed. For the specific meaning of the remainder of the output it
84 is best to consult the apt source code.</para></listitem>
85 </varlistentry>
86
87 <varlistentry><term>stats</term><listitem><para><literal>stats</literal> displays some statistics about the cache.
88 No further arguments are expected. Statistics reported are:
89 <itemizedlist>
90 <listitem><para><literal>Total package names</literal> is the number of package names found
91 in the cache.</para>
92 </listitem>
93
94 <listitem><para><literal>Normal packages</literal> is the number of regular, ordinary package
95 names; these are packages that bear a one-to-one correspondence between
96 their names and the names used by other packages for them in
97 dependencies. The majority of packages fall into this category.</para>
98 </listitem>
99
100 <listitem><para><literal>Pure virtual packages</literal> is the number of packages that exist
101 only as a virtual package name; that is, packages only "provide" the
102 virtual package name, and no package actually uses the name. For
103 instance, "mail-transport-agent" in the Debian GNU/Linux system is a
104 pure virtual package; several packages provide "mail-transport-agent",
105 but there is no package named "mail-transport-agent".</para>
106 </listitem>
107
108 <listitem><para><literal>Single virtual packages</literal> is the number of packages with only
109 one package providing a particular virtual package. For example, in the
110 Debian GNU/Linux system, "X11-text-viewer" is a virtual package, but
111 only one package, xless, provides "X11-text-viewer".</para>
112 </listitem>
113
114 <listitem><para><literal>Mixed virtual packages</literal> is the number of packages that either
115 provide a particular virtual package or have the virtual package name
116 as the package name. For instance, in the Debian GNU/Linux system,
117 "debconf" is both an actual package, and provided by the debconf-tiny
118 package.</para>
119 </listitem>
120
121 <listitem><para><literal>Missing</literal> is the number of package names that were referenced in
122 a dependency but were not provided by any package. Missing packages may
5f4331c4 123 be an evidence if a full distribution is not accessed, or if a package
24f6490f 124 (real or virtual) has been dropped from the distribution. Usually they
308c7d30 125 are referenced from Conflicts or Breaks statements.</para>
24f6490f
AL
126 </listitem>
127
128 <listitem><para><literal>Total distinct</literal> versions is the number of package versions
129 found in the cache; this value is therefore at least equal to the
130 number of total package names. If more than one distribution (both
131 "stable" and "unstable", for instance), is being accessed, this value
132 can be considerably larger than the number of total package names.</para>
133 </listitem>
134
135 <listitem><para><literal>Total dependencies</literal> is the number of dependency relationships
136 claimed by all of the packages in the cache.</para>
137 </listitem>
138 </itemizedlist>
139 </para></listitem>
140 </varlistentry>
141
c086ac18 142 <varlistentry><term>showsrc <replaceable>&synopsis-pkg;</replaceable>…</term>
24f6490f
AL
143 <listitem><para><literal>showsrc</literal> displays all the source package records that match
144 the given package names. All versions are shown, as well as all
145 records that declare the name to be a Binary.</para></listitem>
146 </varlistentry>
147
148 <varlistentry><term>dump</term>
149 <listitem><para><literal>dump</literal> shows a short listing of every package in the cache. It is
150 primarily for debugging.</para></listitem>
151 </varlistentry>
152
153 <varlistentry><term>dumpavail</term>
154 <listitem><para><literal>dumpavail</literal> prints out an available list to stdout. This is
155 suitable for use with &dpkg; and is used by the &dselect; method.</para></listitem>
156 </varlistentry>
157
158 <varlistentry><term>unmet</term>
159 <listitem><para><literal>unmet</literal> displays a summary of all unmet dependencies in the
160 package cache.</para></listitem>
161 </varlistentry>
162
c086ac18 163 <varlistentry><term>show <replaceable>&synopsis-pkg;</replaceable>…</term>
24f6490f 164 <listitem><para><literal>show</literal> performs a function similar to
babb80e1 165 <command>dpkg --print-avail</command>; it displays the package records for the
24f6490f
AL
166 named packages.</para></listitem>
167 </varlistentry>
168
c086ac18 169 <varlistentry><term>search <replaceable>&synopsis-regex;</replaceable>…</term>
24f6490f 170 <listitem><para><literal>search</literal> performs a full text search on all available package
696268f7 171 lists for the POSIX regex pattern given, see
f0270266
MV
172 <citerefentry><refentrytitle><command>regex</command></refentrytitle>
173 <manvolnum>7</manvolnum></citerefentry>.
696268f7 174 It searches the package names and the
24f6490f 175 descriptions for an occurrence of the regular expression and prints out
696268f7
LB
176 the package name and the short description, including virtual package
177 names.
178 If <option>--full</option> is given
24f6490f
AL
179 then output identical to <literal>show</literal> is produced for each matched
180 package, and if <option>--names-only</option> is given then the long description
181 is not searched, only the package name is.</para>
182 <para>
183 Separate arguments can be used to specify multiple search patterns that
184 are and'ed together.</para></listitem>
185 </varlistentry>
186
c086ac18 187 <varlistentry><term>depends <replaceable>&synopsis-pkg;</replaceable>…</term>
24f6490f
AL
188 <listitem><para><literal>depends</literal> shows a listing of each dependency a package has
189 and all the possible other packages that can fulfill that dependency.</para></listitem>
190 </varlistentry>
191
c086ac18 192 <varlistentry><term>rdepends <replaceable>&synopsis-pkg;</replaceable>…</term>
4a5e5089 193 <listitem><para><literal>rdepends</literal> shows a listing of each reverse dependency a
24f6490f
AL
194 package has.</para></listitem>
195 </varlistentry>
196
c086ac18 197 <varlistentry><term>pkgnames [ <replaceable>&synopsis-prefix;</replaceable> ]</term>
3ba36dff 198 <listitem><para>This command prints the name of each package APT knows. The optional
24f6490f
AL
199 argument is a prefix match to filter the name list. The output is suitable
200 for use in a shell tab complete function and the output is generated
201 extremely quickly. This command is best used with the
3ba36dff 202 <option>--generate</option> option.</para>
847d81b8 203 <para>Note that a package which APT knows of is not necessarily available to download,
3ba36dff
DK
204 installable or installed, e.g. virtual packages are also listed in the generated list.
205 </para></listitem>
24f6490f
AL
206 </varlistentry>
207
c086ac18 208 <varlistentry><term>dotty <replaceable>&synopsis-pkg;</replaceable>…</term>
24f6490f
AL
209 <listitem><para><literal>dotty</literal> takes a list of packages on the command line and
210 generates output suitable for use by dotty from the
211 <ulink url="http://www.research.att.com/sw/tools/graphviz/">GraphViz</ulink>
212 package. The result will be a set of nodes and edges representing the
213 relationships between the packages. By default the given packages will
214 trace out all dependent packages; this can produce a very large graph.
215 To limit the output to only the packages listed on the command line,
216 set the <literal>APT::Cache::GivenOnly</literal> option.</para>
217
218 <para>The resulting nodes will have several shapes; normal packages are boxes,
219 pure provides are triangles, mixed provides are diamonds,
220 missing packages are hexagons. Orange boxes mean recursion was stopped
221 [leaf packages], blue lines are pre-depends, green lines are conflicts.</para>
222
223 <para>Caution, dotty cannot graph larger sets of packages.</para></listitem>
224 </varlistentry>
225
c086ac18 226 <varlistentry><term>xvcg <replaceable>&synopsis-pkg;</replaceable></term>
c2c45f40
EL
227 <listitem><para>The same as <literal>dotty</literal>, only for xvcg from the
228 <ulink url="http://rw4.cs.uni-sb.de/users/sander/html/gsvcg1.html">VCG tool</ulink>.
229 </para></listitem></varlistentry>
230
c086ac18 231 <varlistentry><term>policy [ <replaceable>&synopsis-pkg;</replaceable>… ]</term>
335f09c5 232 <listitem><para><literal>policy</literal> is meant to help debug issues relating to the
24f6490f
AL
233 preferences file. With no arguments it will print out the
234 priorities of each source. Otherwise it prints out detailed information
235 about the priority selection of the named package.</para></listitem>
236 </varlistentry>
237
c086ac18 238 <varlistentry><term>madison <replaceable>&synopsis-pkg;</replaceable>…</term>
24f6490f
AL
239 <listitem><para><literal>apt-cache</literal>'s <literal>madison</literal> command attempts to mimic
240 the output format and a subset of the functionality of the Debian
241 archive management tool, <literal>madison</literal>. It displays
242 available versions of a package in a tabular format. Unlike the
243 original <literal>madison</literal>, it can only display information for
244 the architecture for which APT has retrieved package lists
245 (<literal>APT::Architecture</literal>).</para></listitem>
246 </varlistentry>
247 </variablelist>
248 </refsect1>
249
250 <refsect1><title>options</title>
251 &apt-cmdblurb;
252
253 <variablelist>
254 <varlistentry><term><option>-p</option></term><term><option>--pkg-cache</option></term>
255 <listitem><para>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</literal>.</para></listitem>
258 </varlistentry>
259
260 <varlistentry><term><option>-s</option></term><term><option>--src-cache</option></term>
261 <listitem><para>Select the file to store the source cache. The source is used only by
262 <literal>gencaches</literal> and it stores a parsed version of the package
263 information from remote sources. When building the package cache the
584c10c5 264 source cache is used to avoid reparsing all of the package files.
24f6490f
AL
265 Configuration Item: <literal>Dir::Cache::srcpkgcache</literal>.</para></listitem>
266 </varlistentry>
267
268 <varlistentry><term><option>-q</option></term><term><option>--quiet</option></term>
269 <listitem><para>Quiet; produces output suitable for logging, omitting progress indicators.
270 More q's will produce more quietness up to a maximum of 2. You can also use
271 <option>-q=#</option> to set the quietness level, overriding the configuration file.
272 Configuration Item: <literal>quiet</literal>.</para></listitem>
273 </varlistentry>
274
275 <varlistentry><term><option>-i</option></term><term><option>--important</option></term>
5aa95c86 276 <listitem><para>Print only important dependencies; for use with unmet and depends. Causes only Depends and
24f6490f
AL
277 Pre-Depends relations to be printed.
278 Configuration Item: <literal>APT::Cache::Important</literal>.</para></listitem>
279 </varlistentry>
280
fe1af091
DK
281 <varlistentry><term><option>--no-pre-depends</option></term>
282 <term><option>--no-depends</option></term>
283 <term><option>--no-recommends</option></term>
284 <term><option>--no-suggests</option></term>
285 <term><option>--no-conflicts</option></term>
286 <term><option>--no-breaks</option></term>
287 <term><option>--no-replaces</option></term>
288 <term><option>--no-enhances</option></term>
289 <listitem><para>Per default the <literal>depends</literal> and
1fc8c922 290 <literal>rdepends</literal> print all dependencies. This can be tweaked with
fe1af091
DK
291 these flags which will omit the specified dependency type.
292 Configuration Item: <literal>APT::Cache::Show<replaceable>DependencyType</replaceable></literal>
293 e.g. <literal>APT::Cache::ShowRecommends</literal>.</para></listitem>
294 </varlistentry>
24f6490f
AL
295 <varlistentry><term><option>-f</option></term><term><option>--full</option></term>
296 <listitem><para>Print full package records when searching.
297 Configuration Item: <literal>APT::Cache::ShowFull</literal>.</para></listitem>
298 </varlistentry>
299
300 <varlistentry><term><option>-a</option></term><term><option>--all-versions</option></term>
301 <listitem><para>Print full records for all available versions. This is the
302 default; to turn it off, use <option>--no-all-versions</option>.
303 If <option>--no-all-versions</option> is specified, only the candidate version
304 will displayed (the one which would be selected for installation).
305 This option is only applicable to the <literal>show</literal> command.
306 Configuration Item: <literal>APT::Cache::AllVersions</literal>.</para></listitem>
307 </varlistentry>
308
309 <varlistentry><term><option>-g</option></term><term><option>--generate</option></term>
310 <listitem><para>Perform automatic package cache regeneration, rather than use the cache
311 as it is. This is the default; to turn it off, use <option>--no-generate</option>.
312 Configuration Item: <literal>APT::Cache::Generate</literal>.</para></listitem>
313 </varlistentry>
314
315 <varlistentry><term><option>--names-only</option></term><term><option>-n</option></term>
316 <listitem><para>Only search on the package names, not the long descriptions.
317 Configuration Item: <literal>APT::Cache::NamesOnly</literal>.</para></listitem>
318 </varlistentry>
319
320 <varlistentry><term><option>--all-names</option></term>
321 <listitem><para>Make <literal>pkgnames</literal> print all names, including virtual packages
322 and missing dependencies.
323 Configuration Item: <literal>APT::Cache::AllNames</literal>.</para></listitem>
324 </varlistentry>
325
326 <varlistentry><term><option>--recurse</option></term>
327 <listitem><para>Make <literal>depends</literal> and <literal>rdepends</literal> recursive so
328 that all packages mentioned are printed once.
329 Configuration Item: <literal>APT::Cache::RecurseDepends</literal>.</para></listitem>
330 </varlistentry>
331
332 <varlistentry><term><option>--installed</option></term>
333 <listitem><para>
334 Limit the output of <literal>depends</literal> and <literal>rdepends</literal> to
335 packages which are currently installed.
336 Configuration Item: <literal>APT::Cache::Installed</literal>.</para></listitem>
337 </varlistentry>
338
339 &apt-commonoptions;
340
341 </variablelist>
342 </refsect1>
343
344 <refsect1><title>Files</title>
345 <variablelist>
1221c3a3
DK
346 &file-sourceslist;
347 &file-statelists;
24f6490f
AL
348 </variablelist>
349 </refsect1>
350
351 <refsect1><title>See Also</title>
352 <para>&apt-conf;, &sources-list;, &apt-get;
353 </para>
354 </refsect1>
355
356 <refsect1><title>Diagnostics</title>
357 <para><command>apt-cache</command> returns zero on normal operation, decimal 100 on error.
358 </para>
359 </refsect1>
360
361 &manbugs;
24f6490f
AL
362
363</refentry>