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