[apt.git] / doc / apt-cache.8
1 .\" This manpage has been automatically generated by docbook2man 
2 .\" from a DocBook document.  This tool can be found at:
3 .\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
4 .\" Please send any bug reports, improvements, comments, patches, 
5 .\" etc. to Steve Cheng <steve@ggi-project.org>.
6 .TH "APT-CACHE" "8" "29 May 2006" "" ""
9 apt-cache \- APT package handling utility -- cache manipulator
12 \fBapt-cache\fR [ \fB-hvsn\fR ] [ \fB-o=\fIconfig string\fB\fR ] [ \fB-c=\fIfile\fB\fR ] { \fBadd  \fIfile\fB\fI ...\fB\fR | \fBgencaches\fR | \fBshowpkg  \fIpkg\fB\fI ...\fB\fR | \fBshowsrc  \fIpkg\fB\fI ...\fB\fR | \fBstats\fR | \fBdump\fR | \fBdumpavail\fR | \fBunmet\fR | \fBsearch  \fIregex\fB\fR | \fBshow  \fIpkg\fB\fI ...\fB\fR | \fBdepends  \fIpkg\fB\fI ...\fB\fR | \fBwhatdepends  \fIpkg\fB\fI ...\fB\fR | \fBpkgnames  \fIprefix\fB\fR | \fBdotty  \fIpkg\fB\fI ...\fB\fR | \fBpolicy  \fIpkgs\fB\fI ...\fB\fR }
15 .PP
16 \fBapt-cache\fR performs a variety of operations on APT's package 
17 cache. \fBapt-cache\fR does not manipulate the state of the system 
18 but does provide operations to search and generate interesting output 
19 from the package metadata.
20 .PP
21 Unless the \fB-h\fR, or \fB--help\fR option is given, one of the
22 commands below must be present.
23 .TP
24 \fBadd \fIfile(s)\fB\fR
25 add adds the named package index files to the package cache.
26 This is for debugging only.
27 .TP
28 \fBgencaches\fR
29 gencaches performs the same operation as 
30 \fBapt-get check\fR\&. It builds the source and package caches from 
31 the sources in \fB\fIsources.list\fB\fR(5) and from \fI/var/lib/rpm/\fR\&.
32 .TP
33 \fBshowpkg \fIpkg(s)\fB\fR
34 showpkg displays information about the packages listed on the 
35 command line. Remaining arguments are package names. The available 
36 versions and reverse dependencies of each package listed are listed, as 
37 well as forward dependencies for each version. Forward (normal) 
38 dependencies are those packages upon which the package in question 
39 depends; reverse dependencies are those packages that depend upon the 
40 package in question. Thus, forward dependencies must be satisfied for a 
41 package, but reverse dependencies need not be.
42 For instance, \fBapt-cache showpkg libreadline2\fR would produce 
43 output similar to the following:
46 .nf
47 Package: libreadline2
48 Versions: 2.1-12(/var/lib/apt/lists/foo_Packages),
49 Reverse Depends: 
50   libreadlineg2,libreadline2
51   libreadline2-altdev,libreadline2
52 Dependencies:
53 2.1-12 - libc5 (2 5.4.0-0) ncurses3.0 (0 (null))
54 Provides:
55 2.1-12 - 
56 Reverse Provides: 
57 .fi
59 Thus it may be seen that libreadline2, version 2.1-12, depends on libc5 and
60 ncurses3.0 which must be installed for libreadline2 to work. 
61 In turn, libreadlineg2 and libreadline2-altdev depend on libreadline2. If
62 libreadline2 is installed, libc5 and ncurses3.0 (and ldso) must also be
63 installed; libreadlineg2 and libreadline2-altdev do not have to be
64 installed. For the specific meaning of the remainder of the output it
65 is best to consult the apt source code.
66 .TP
67 \fBstats\fR
68 stats displays some statistics about the cache.
69 No further arguments are expected. Statistics reported are:
70 .RS
71 .TP 0.2i
72 \(bu
73 Total package names is the number of package names found 
74 in the cache.
75 .TP 0.2i
76 \(bu
77 Normal packages is the number of regular, ordinary package 
78 names; these are packages that bear a one-to-one correspondence between 
79 their names and the names used by other packages for them in 
80 dependencies. The majority of packages fall into this category.
81 .TP 0.2i
82 \(bu
83 Pure virtual packages is the number of packages that exist 
84 only as a virtual package name; that is, packages only "provide" the 
85 virtual package name, and no package actually uses the name. For 
86 instance, "mail-transport-agent" in the Debian GNU/Linux system is a 
87 pure virtual package; several packages provide "mail-transport-agent", 
88 but there is no package named "mail-transport-agent".
89 .TP 0.2i
90 \(bu
91 Single virtual packages is the number of packages with only 
92 one package providing a particular virtual package. For example, in the
93 Debian GNU/Linux system, "X11-text-viewer" is a virtual package, but 
94 only one package, xless, provides "X11-text-viewer".
95 .TP 0.2i
96 \(bu
97 Mixed virtual packages is the number of packages that either 
98 provide a particular virtual package or have the virtual package name 
99 as the package name. For instance, in the Debian GNU/Linux system, 
100 "debconf" is both an actual package, and provided by the debconf-tiny
101 package.
102 .TP 0.2i
103 \(bu
104 Missing is the number of package names that were referenced in
105 a dependency but were not provided by any package. Missing packages may 
106 be in evidence if a full distribution is not accessed, or if a package
107 (real or virtual) has been dropped from the distribution. Usually they
108 are referenced from Conflicts statements.
109 .TP 0.2i
110 \(bu
111 Total distinct versions is the number of package versions 
112 found in the cache; this value is therefore at least equal to the 
113 number of total package names. If more than one distribution (both 
114 "stable" and "unstable", for instance), is being accessed, this value 
115 can be considerably larger than the number of total package names.
116 .TP 0.2i
117 \(bu
118 Total dependencies is the number of dependency relationships 
119 claimed by all of the packages in the cache.
120 .RE
121 .TP
122 \fBshowsrc \fIpkg(s)\fB\fR
123 showsrc displays all the source package records that match
124 the given package names. All versions are shown, as well as all 
125 records that declare the name to be a Binary.
126 .TP
127 \fBdump\fR
128 dump shows a short listing of every package in the cache. It is 
129 primarily for debugging.
130 .TP
131 \fBdumpavail\fR
132 dumpavail prints out an available list to stdout.
133 .TP
134 \fBunmet\fR
135 unmet displays a summary of all unmet dependencies in the 
136 package cache.
137 .TP
138 \fBshow \fIpkg(s)\fB\fR
139 Displays the package records for the named packages.
140 .TP
141 \fBsearch \fIregex [ regex ... ]\fB\fR
142 search performs a full text search on all available package
143 lists for the regex pattern given. It searches the package names and the
144 descriptions for an occurrence of the regular expression and prints out
145 the package name and the short description. If \fB--full\fR is given
146 then output identical to show is produced for each matched
147 package, and if \fB--names-only\fR is given then the long description
148 is not searched, only the package name is.
150 Separate arguments can be used to specify multiple search patterns that 
151 are and'ed together.
152 .TP
153 \fBdepends \fIpkg(s)\fB\fR
154 depends shows a listing of each dependency a package has 
155 and all the possible other packages that can fulfill that dependency.
156 .TP
157 \fBwhatdepends \fIpkg(s)\fB\fR
158 whatdepends shows a listing of what depends on a package.
159 .TP
160 \fBwhatprovides \fIpkg(s)\fB\fR
161 whatprovides shows a listing of package which provides a
162 dependency.
163 .TP
164 \fBpkgnames \fI[ prefix ]\fB\fR
165 This command prints the name of each package in the system. The optional
166 argument is a prefix match to filter the name list. The output is suitable
167 for use in a shell tab complete function and the output is generated 
168 extremely quickly. This command is best used with the 
169 \fB--generate\fR option.
170 .TP
171 \fBdotty \fIpkg(s)\fB\fR
172 dotty takes a list of packages on the command line and 
173 generates output suitable for use by dotty from the 
174 GraphViz <URL:http://www.research.att.com/sw/tools/graphviz/>
175 package. The result will be a set of nodes and edges representing the 
176 relationships between the packages. By default the given packages will 
177 trace out all dependent packages; this can produce a very large graph. 
178 To limit the output to only the packages listed on the command line,
179 set the APT::Cache::GivenOnly option.
181 The resulting nodes will have several shapes; normal packages are boxes,
182 pure provides are triangles, mixed provides are diamonds, 
183 missing packages are hexagons. Orange boxes mean recursion was stopped 
184 [leaf packages], blue lines are pre-depends, green lines are conflicts.
186 Caution, dotty cannot graph larger sets of packages.
187 .TP
188 \fBpolicy \fI[ pkg(s) ]\fB\fR
189 policy is ment to help debug issues relating to the 
190 preferences file. With no arguments it will print out the 
191 priorities of each source. Otherwise it prints out detailed information
192 about the priority selection of the named package.
194 .PP
195 All command line options may be set using the configuration file, the
196 descriptions indicate the configuration option to set. For boolean
197 options you can override the config file by using something like 
198 \fB-f-\fR,\fB--no-f\fR, \fB-f=no\fR or several other variations.
199 .TP
200 \fB-p\fR
201 .TP
202 \fB--pkg-cache\fR
203 Select the file to store the package cache. The package cache is the 
204 primary cache used by all operations.
205 Configuration Item: Dir::Cache::pkgcache\&.
206 .TP
207 \fB-s\fR
208 .TP
209 \fB--src-cache\fR
210 Select the file to store the source cache. The source is used only by
211 gencaches and it stores a parsed version of the package 
212 information from remote sources. When building the package cache the 
213 source cache is used to advoid reparsing all of the package files.
214 Configuration Item: Dir::Cache::srcpkgcache\&.
215 .TP
216 \fB-q\fR
217 .TP
218 \fB--quiet\fR
219 Quiet; produces output suitable for logging, omitting progress indicators.
220 More q's will produce more quietness up to a maximum of 2. You can also use
221 \fB-q=#\fR to set the quietness level, overriding the configuration file.
222 Configuration Item: quiet\&.
223 .TP
224 \fB-i\fR
225 .TP
226 \fB--important\fR
227 Print only important dependencies; for use with unmet. Causes only Depends and 
228 Pre-Depends relations to be printed.
229 Configuration Item: APT::Cache::Important\&.
230 .TP
231 \fB-f\fR
232 .TP
233 \fB--full\fR
234 Print full package records when searching. 
235 Configuration Item: APT::Cache::ShowFull\&.
236 .TP
237 \fB-a\fR
238 .TP
239 \fB--all-versions\fR
240 Print full records for all available versions. This is the
241 default; to turn it off, use \fB--no-all-versions\fR\&.
242 If \fB--no-all-versions\fR is specified, only the candidate version
243 will displayed (the one which would be selected for installation).
244 This option is only applicable to  the show command.
245 Configuration Item: APT::Cache::AllVersions\&.
246 .TP
247 \fB-g\fR
248 .TP
249 \fB--generate\fR
250 Perform automatic package cache regeneration, rather than use the cache 
251 as it is. This is the default; to turn it off, use \fB--no-generate\fR\&.
252 Configuration Item: APT::Cache::Generate\&.
253 .TP
254 \fB--names-only\fR
255 .TP
256 \fB-n\fR
257 Only search on the package names, not the long descriptions. 
258 Configuration Item: APT::Cache::NamesOnly\&.
259 .TP
260 \fB--all-names\fR
261 Make pkgnames print all names, including virtual packages 
262 and missing dependencies. 
263 Configuration Item: APT::Cache::AllNames\&.
264 .TP
265 \fB--recurse\fR
266 Make depends recursive so that all packages mentioned are 
267 printed once.
268 Configuration Item: APT::Cache::RecurseDepends\&.
269 .TP
270 \fB-h\fR
271 .TP
272 \fB--help\fR
273 Show a short usage summary.
274 .TP
275 \fB-v\fR
276 .TP
277 \fB--version\fR
278 Show the program version.
279 .TP
280 \fB-c\fR
281 .TP
282 \fB--config-file\fR
283 Configuration File; Specify a configuration file to use. 
284 The program will read the default configuration file and then this 
285 configuration file. See \fB\fIapt.conf\fB\fR(5) for syntax information.     
286 .TP
287 \fB-o\fR
288 .TP
289 \fB--option\fR
290 Set a Configuration Option; This will set an arbitrary configuration 
291 option. The syntax is \fB-o Foo::Bar=bar\fR\&.
292 .SH "FILES"
293 .TP
294 \fB\fI/etc/apt/sources.list\fB\fR
295 Locations to fetch packages from.
296 Configuration Item: Dir::Etc::SourceList\&.
297 .TP
298 \fB\fI/var/lib/apt/lists/\fB\fR
299 Storage area for state information for each package resource specified in
300 \fB\fIsources.list\fB\fR(5)
301 Configuration Item: Dir::State::Lists\&.
302 .TP
303 \fB\fI/var/lib/apt/lists/partial/\fB\fR
304 Storage area for state information in transit.
305 Configuration Item: Dir::State::Lists (implicit partial).
306 .SH "SEE ALSO"
307 .PP
308 \fB\fIapt.conf\fB\fR(5), \fB\fIsources.list\fB\fR(5), \fBapt-get\fR(8)
310 .PP
311 \fBapt-cache\fR returns zero on normal operation, decimal 100 on error.
312 .SH "BUGS"
313 .PP
314 See the APT bug page <URL:http://bugs.debian.org/src:apt>\&.  
315 If you wish to report a bug in APT, please see
316 \fI/usr/share/doc/debian/bug-reporting.txt\fR or the \fBreportbug\fR(1) command.
317 .SH "AUTHOR"
318 .PP
319 APT was written by the APT team <apt@packages.debian.org>\&.