man: Drop AUTHORS sections in favor of comments in source
[dpkg/dpkg.git] / man / dpkg-query.1
1 .\" dpkg manual page - dpkg-query(1)
2 .\"
3 .\" Copyright © 2001 Wichert Akkerman <wakkerma@debian.org>
4 .\" Copyright © 2006-2007 Frank Lichtenheld <djpig@debian.org>
5 .\" Copyright © 2006-2011 Guillem Jover <guillem@debian.org>
6 .\" Copyright © 2008-2011 Raphaël Hertzog <hertzog@debian.org>
7 .\"
8 .\" This is free software; you can redistribute it and/or modify
9 .\" it under the terms of the GNU General Public License as published by
10 .\" the Free Software Foundation; either version 2 of the License, or
11 .\" (at your option) any later version.
12 .\"
13 .\" This is distributed in the hope that it will be useful,
14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 .\" GNU General Public License for more details.
17 .\"
18 .\" You should have received a copy of the GNU General Public License
19 .\" along with this program.  If not, see <http://www.gnu.org/licenses/>.
20 .
21 .TH dpkg\-query 1 "2012-01-11" "Debian Project" "dpkg suite"
22 .SH NAME
23 dpkg\-query \- a tool to query the dpkg database
24 .
25 .SH SYNOPSIS
26 .B dpkg\-query
27 .RI [ option "...] " command
28 .
29 .SH DESCRIPTION
30 \fBdpkg\-query\fP is a tool to show information about packages listed in
31 the \fBdpkg\fP database.
32 .
33 .SH COMMANDS
34 .TP
35 .BR \-l ", " \-\-list " [\fIpackage-name-pattern\fP...]"
36 List packages matching given pattern. If no \fIpackage-name-pattern\fP
37 is given, list all packages in \fI/var/lib/dpkg/status\fP, excluding
38 the ones marked as not-installed (i.e. those which have been previously
39 purged). Normal shell wildchars are allowed
40 in \fIpackage-name-pattern\fP. Please note you will probably have to
41 quote \fIpackage-name-pattern\fP to prevent the shell from performing
42 filename expansion. For example this will list all package names starting
43 with \*(lqlibc6\*(rq:
44
45 .nf
46   \fBdpkg\-query \-l \(aqlibc6*\(aq\fP
47 .fi
48
49 The first three columns of the output show the desired action, the package
50 status, and errors, in that order.
51
52 Desired action:
53 .nf
54   u = Unknown
55   i = Install
56   h = Hold
57   r = Remove
58   p = Purge
59 .fi
60
61 Package status:
62 .nf
63   n = Not-installed
64   c = Config-files
65   H = Half-installed
66   U = Unpacked
67   F = Half-configured
68   W = Triggers-awaiting
69   t = Triggers-pending
70   i = Installed
71 .fi
72
73 Error flags:
74 .nf
75   <empty> = (none)
76   R = Reinst-required
77 .fi
78
79 An uppercase status or error letter indicates the package is likely to
80 cause severe problems. Please refer to \fBdpkg\fP(1) for information
81 about the above states and flags.
82
83 The output format of this option is not configurable, but varies
84 automatically to fit the terminal width. It is intended for human
85 readers, and is not easily machine-readable. See \fB\-W\fP (\fB\-\-show\fP)
86 and \fB\-\-showformat\fP for a way to configure the output format.
87 .TP
88 .BR \-W ", " \-\-show " [\fIpackage-name-pattern\fP...]"
89 Just like the \fB\-\-list\fP option this will list all packages matching
90 the given pattern. However the output can be customized using the
91 \fB\-\-showformat\fP option.
92 The default output format gives one line per matching package, each line
93 having the name and installed version of the package, separated by a tab.
94 .TP
95 .BR \-s ", " \-\-status " \fIpackage-name\fP..."
96 Report status of specified package. This just displays the entry in
97 the installed package status database. When multiple \fIpackage-name\fP
98 are listed, the requested status entries are separated by an empty line.
99 .TP
100 .BR \-L ", " \-\-listfiles " \fIpackage-name\fP..."
101 List files installed to your system from \fIpackage-name\fP. When multiple
102 \fIpackage-name\fP are listed, the requested lists of files are separated
103 by an empty line. However, note that files created by package-specific
104 installation-scripts are not listed.
105 .TP
106 .BR \-c ", " \-\-control\-path " \fIpackage-name\fP [\fIcontrol-file\fP]"
107 List paths for control files installed to your system from \fIpackage-name\fP.
108 If \fIcontrol-file\fP is specified then only list the path for that control
109 file if it is present. \fBWarning\fP: this command is semi-public, it should
110 be used only as a last resort solution, and if no other interface is
111 available. It might get deprecated later on if better interfaces or the
112 current architectural deficiencies have been solved.
113 .TP
114 .BR \-S ", " \-\-search " \fIfilename-search-pattern\fP..."
115 Search for packages that own files corresponding to the given pattern.
116 Standard shell wildchars can be used in the pattern.
117 This command will not list extra files created by maintainer scripts,
118 nor will it list alternatives.
119 .TP
120 .BR \-p ", " \-\-print\-avail " \fIpackage-name\fP..."
121 Display details about \fIpackage-name\fP, as found in
122 \fI/var/lib/dpkg/available\fP. When multiple \fIpackage-name\fP are
123 listed, the requested \fIavailable\fP entries are separated by an empty
124 line.
125
126 Users of APT-based frontends
127 should use \fBapt\-cache show\fP \fIpackage-name\fP instead
128 as the \fIavailable\fP file is only kept up-to-date when
129 using \fBdselect\fP.
130 .TP
131 .BR \-h ", " \-\-help
132 Show the usage message and exit.
133 .TP
134 .B \-\-version
135 Show the version and exit.
136 .
137 .SH OPTIONS
138 .TP
139 .BI \-\-admindir= dir
140 Change the location of the \fBdpkg\fR database. The default location is
141 \fI/var/lib/dpkg\fP.
142 .TP
143 .BR \-f ", " \-\-showformat=\fIformat\fR
144 This option is used to specify the format of the output \fB\-\-show\fP
145 will produce. The format is a string that will be output for each package
146 listed.
147
148 In the format string, \(lq\fB\e\fP\(rq introduces escapes:
149
150 .nf
151     \fB\en\fP  newline
152     \fB\er\fP  carriage return
153     \fB\et\fP  tab
154 .fi
155
156 \(lq\fB\e\fP\(rq before any other character suppresses any special
157 meaning of the following character, which is useful for \(lq\fB\e\fP\(rq
158 and \(lq\fB$\fP\(rq.
159
160 Package information can be included by inserting
161 variable references to package fields using the syntax
162 \(lq\fB${\fP\fIfield\fR[\fB;\fP\fIwidth\fR]\fB}\fP\(rq. Fields are
163 printed right-aligned unless the width is negative in which case left
164 alignment will be used. The following \fIfield\fRs are recognised but
165 they are not necessarily available in the status file (only internal
166 fields or fields stored in the binary package end up in it):
167
168 .nf
169     \fBArchitecture\fP
170     \fBBugs\fP
171     \fBConffiles\fP (internal)
172     \fBConfig\-Version\fP (internal)
173     \fBConflicts\fP
174     \fBBreaks\fP
175     \fBDepends\fP
176     \fBDescription\fP
177     \fBEnhances\fP
178     \fBEssential\fP
179     \fBFilename\fP (internal, front-end related)
180     \fBHomepage\fP
181     \fBInstalled\-Size\fP
182     \fBMD5sum\fP (internal, front-end related)
183     \fBMSDOS\-Filename\fP (internal, front-end related)
184     \fBMaintainer\fP
185     \fBOrigin\fP
186     \fBPackage\fP
187     \fBPre\-Depends\fP
188     \fBPriority\fP
189     \fBProvides\fP
190     \fBRecommends\fP
191     \fBReplaces\fP
192     \fBRevision\fP (obsolete)
193     \fBSection\fP
194     \fBSize\fP (internal, front-end related)
195     \fBSource\fP
196     \fBStatus\fP (internal)
197     \fBSuggests\fP
198     \fBTag\fP (usually not in .deb but in repository Packages files)
199     \fBTriggers\-Awaited\fP (internal)
200     \fBTriggers\-Pending\fP (internal)
201     \fBVersion\fP
202 .fi
203
204 The following are virtual fields, generated by \fBdpkg\-query\fP from
205 values from other fields (note that these do not use valid names for
206 fields in control files):
207
208 .nf
209     \fBbinary:Package\fP
210     \fBbinary:Summary\fP
211     \fBdb:Status\-Abbrev\fP
212     \fBsource:Package\fP
213     \fBsource:Version\fP
214 .fi
215
216 The default format string is \(lq\fB${Package}\et${Version}\en\fP\(rq.
217 Actually, all other fields found in the status file (i.e. user defined
218 fields) can be requested, too. They will be printed as-is, though, no
219 conversion nor error checking is done on them.
220 To get the name of the dpkg maintainer and the installed version, you could
221 run:
222
223 .nf
224   \fBdpkg\-query \-W \-f=\(aq${Package} ${Version}\\t${Maintainer}\\n\(aq dpkg\fP
225 .fi
226 .
227 .SH "EXIT STATUS"
228 .TP
229 .B 0
230 The requested query was successfully performed.
231 .TP
232 .B 1
233 Problems were encountered while parsing the command line or performing the
234 query, including no file or package being found (except for \-\-control\-path).
235 .
236 .SH ENVIRONMENT
237 .TP
238 .B DPKG_ADMINDIR
239 If set and the \fB\-\-admindir\fP option has not been specified, it will
240 be used as the dpkg data directory.
241 .TP
242 \fBCOLUMNS\fP
243 This setting influences the output of the \fB\-\-list\fP option by changing
244 the width of its output.
245 .
246 .SH SEE ALSO
247 .BR dpkg (1).
248