Debian Codegraph @

upstream/debian-unstable/man7/rpm-queryformat.7

raw
1 .\" Generated by scdoc 1.11.4
2 .\" Complete documentation for this program is not available as a GNU info page
3 .ie \n(.g .ds Aq \(aq
4 .el .ds Aq '
5 .nh
6 .ad l
7 .\" Begin generated content:
8 .TH "RPM-QUERYFORMAT" "7" "2026-04-10" "RPM 6.0.1"
9 .PP
10 .SH NAME
11 \fBrpm-queryformat\fR - RPM query mini-language
12 .PP
13 .SH SYNOPSIS
14 .SS Query format
15 [\fIPLACEHOLDER\fR|\fIITERATOR\fR|\fIEXPRESSION\fR|\fITEXT\fR .\&.\&.\&]
16 .PP
17 .SS Placeholder
18 \fB%\fR[\fIWIDTH\fR]\fB{\fR\fITAG\fR[\fB:\fR\fIFORMAT\fR]\fB}\fR
19 .PP
20 .SS Iterator
21 \fB[\fR\fIQUERYFORMAT\fR .\&.\&.\&\fB]\fR
22 .PP
23 Note: Square brackets are literal and \fIQUERYFORMAT\fR must contain an array
24 placeholder.\&
25 .PP
26 .SS Expression
27 \fB%|\fR\fITAG\fR\fB?\&{\fR\fIPRESENT\fR\fB}:{\fR\fIABSENT\fR\fB}|\fR
28 .PP
29 Note: Vertical bars are literal, \fIPRESENT\fR and \fIABSENT\fR are query formats.\&
30 .PP
31 .SH DESCRIPTION
32 .PP
33 RPM supports a simple query language for extracting header data to plain text.\&
34 Its syntax resembles that of \fBprintf\fR(3) where header tags enclosed in \fB%{\fR and
35 \fB}\fR, for example \fB%{NAME}\fR, are used as placeholders.\& A string written in this
36 syntax is called a \fIquery format\fR.\&
37 .PP
38 Query formats are currently accepted in the following places:
39 .PP
40 .PD 0
41 .IP 1. 4
42 Query operations with \fBrpm\fR(8), as a way to control the output (see
43 \fB--queryformat\fR)
44 .IP 2. 4
45 Runtime scriptlets in \fBrpm-spec\fR(5) files, to access arbitrary header data at
46 runtime
47 .IP 3. 4
48 Configuration macros in \fBrpm-config\fR(5) and \fBrpmbuild-config\fR(5), such as
49 \fB%_query_all_fmt\fR or \fB%_rpmfilename\fR
50 .PD
51 .PP
52 See the \fBEXAMPLES\fR section for more details.\&
53 .PP
54 .SH SYNTAX
55 .PP
56 A valid query format is composed of optional literal text and zero or more
57 \fIplaceholders\fR.\& A placeholder has the following syntax:
58 .PP
59 .nf
60 .RS 4
61 %[WIDTH]{TAG[:FORMAT]}
62 .fi
63 .RE
64 .PP
65 When RPM produces output according to a query format, it substitutes each
66 placeholder with the \fITAG\fR data from the queried package and formats the data
67 according to the specified \fIWIDTH\fR and \fIFORMAT\fR (if given).\& The rest of the
68 query format is copied to the output unchanged.\&
69 .PP
70 Special characters such as \fB\en\fR or \fB\et\fR, with the exception of \fB\e0\fR, are also
71 supported.\& Curly braces, the percent sign and the backslash may be escaped with
72 a backslash.\&
73 .PP
74 The individual components of a placeholder, as well as some additional language
75 features, are described in the subsections below.\&
76 .PP
77 .SS Tags
78 .PP
79 Every RPM package contains a key-value store (the \fIheader\fR) that represents the
80 package'\&s properties, such as its name, version or file list.\& The keys in this
81 store are called \fItags\fR, and can be used in a query format as placeholders for
82 the values (\fIdata\fR) they point to.\& The data is either a single \fIscalar\fR (string,
83 integer or binary blob), or an \fIarray\fR (argv) of multiple scalars of the same
84 type.\&
85 .PP
86 To obtain a list of all tags supported by the installed version of RPM, run the
87 following command:
88 .PP
89 .nf
90 .RS 4
91 rpm -v --querytags
92 .fi
93 .RE
94 .PP
95 This will print a list of available tags, along with their internal numbers and
96 types, for example:
97 .PP
98 .nf
99 .RS 4
100 BASENAMES 1117 argv
101 BUILDHOST 1007 string
102 BUILDTIME 1006 int32
103 DESCRIPTION 1005 i18nstring
104 EPOCH 1003 int32
105 INSTALLTIME 1008 int32
106 NAME 1000 string
107 RELEASE 1002 string
108 SIZE 1009 int32
109 SUMMARY 1004 i18nstring
110 VERSION 1001 string
111 .fi
112 .RE
113 .PP
114 Tags are case-insensitive.\& Each tag also has an implicit variant with the
115 \fBRPMTAG_\fR prefix, such as \fBRPMTAG_NAME\fR.\& Both variants can be used in a query
116 format interchangeably.\&
117 .PP
118 See the tags documentation in \fBSEE ALSO\fR for more details.\&
119 .PP
120 .SS Formats
121 .PP
122 Each tag is printed in a specific output \fIFORMAT\fR.\& When no format is specified,
123 the default \fB:string\fR is used which displays a bare-bones representation of the
124 data.\& You can specify a different format by appending its name after a colon,
125 for example:
126 .PP
127 .nf
128 .RS 4
129 %{INSTALLTIME:date}
130 .fi
131 .RE
132 .PP
133 This is useful for tags that are not stored in human-readable form, such as
134 sizes, dates or signatures.\& Some formats allow for performing more complex
135 transformations of the data, such as encoding it in base64 or wrapping it in
136 JSON syntax.\&
137 .PP
138 The following formats are currently available:
139 .PP
140 .TS
141 l lx
142 l lx
143 l lx
144 l lx
145 l lx
146 l lx
147 l lx
148 l lx
149 l lx
150 l lx
151 l lx
152 l lx
153 l lx
154 l lx
155 l lx
156 l lx
157 l lx
158 l lx
159 l lx
160 l lx
161 l lx
162 l lx
163 l lx
164 l lx
165 l lx
166 l lx
167 l lx.
168 T{
169 \fBName\fR
170 T} T{
171 \fBDescription\fR
172 T}
173 T{
174 \fB:armor\fR
175 T} T{
176 Wrap a public key in ASCII armor
177 T}
178 T{
179 \fB:arraysize\fR
180 T} T{
181 Display number of elements in array tags
182 T}
183 T{
184 \fB:base64\fR
185 T} T{
186 Encode binary data using base64
187 T}
188 T{
189 \fB:date\fR
190 T} T{
191 Use \fBstrftime\fR(3) "%c" format
192 T}
193 T{
194 \fB:day\fR
195 T} T{
196 Use \fBstrftime\fR(3) "%a %b %d %Y" format
197 T}
198 T{
199 \fB:depflags\fR
200 T} T{
201 Format dependency comparison operator
202 T}
203 T{
204 \fB:deptype\fR
205 T} T{
206 Format dependency type
207 T}
208 T{
209 \fB:expand\fR
210 T} T{
211 Perform macro expansion
212 T}
213 T{
214 \fB:fflags\fR
215 T} T{
216 Format file flags
217 T}
218 T{
219 \fB:fstate\fR
220 T} T{
221 Format file state
222 T}
223 T{
224 \fB:fstatus\fR
225 T} T{
226 Format file verify status
227 T}
228 T{
229 \fB:hashalgo\fR
230 T} T{
231 Display hash algorithm name
232 T}
233 T{
234 \fB:hex\fR
235 T} T{
236 Format in hexadecimal
237 T}
238 T{
239 \fB:octal\fR
240 T} T{
241 Format in octal
242 T}
243 T{
244 \fB:humaniec\fR
245 T} T{
246 Human readable number (in IEC 80000) where K = 1024, M = 1048576, .\&.\&.\&
247 T}
248 T{
249 \fB:humansi\fR
250 T} T{
251 Human readable number (in SI) where K = 1000, M = 1000000, .\&.\&.\&
252 T}
253 T{
254 \fB:json\fR
255 T} T{
256 Wrap data in JSON
257 T}
258 T{
259 \fB:perms\fR
260 T} T{
261 Format file permissions
262 T}
263 T{
264 \fB:pgpsig\fR
265 T} T{
266 Display signature fingerprint and time
267 T}
268 T{
269 \fB:shescape\fR
270 T} T{
271 Escape single quotes for use in a script
272 T}
273 T{
274 \fB:string\fR
275 T} T{
276 Display string format (default)
277 T}
278 T{
279 \fB:tagname\fR
280 T} T{
281 Display tag name
282 T}
283 T{
284 \fB:tagnum\fR
285 T} T{
286 Display tag number
287 T}
288 T{
289 \fB:triggertype\fR
290 T} T{
291 Display trigger suffix
292 T}
293 T{
294 \fB:vflags\fR
295 T} T{
296 Format file verification flags
297 T}
298 T{
299 \fB:xml\fR
300 T} T{
301 Wrap data in simple XML markup
302 T}
303 .TE
304 .sp 1
305 Note that some formats are type specific, which means they can only be used with
306 a specific tag type.\& If you attempt to use them with an incompatible type, RPM
307 will replace them with a placeholder text.\& For example, the following query
308 format will result in the output "(not a number)":
309 .PP
310 .nf
311 .RS 4
312 %{NAME:date}
313 .fi
314 .RE
315 .PP
316 Similarly, if a tag is not present in the queried package, it will be replaced
317 with the text "(none)".\&
318 .PP
319 .SS Width
320 .PP
321 You can specify the minimum \fIWIDTH\fR of the data when printed, by placing a
322 number in between the \fB%\fR and \fB{\fR characters, similarly to field width used in
323 \fBprintf\fR(3).\& Optionally, prefix the number with the minus sign to left-justify
324 the text.\&
325 .PP
326 .SS Iterators
327 .PP
328 Tags pointing to arrays may be expanded to the individual elements by using
329 \fIiterators\fR.\& An iterator is a query (sub-)format enclosed in square brackets
330 that contains a placeholder for an array, for example:
331 .PP
332 .nf
333 .RS 4
334 [%{FILENAMES}\\n]
335 .fi
336 .RE
337 .PP
338 RPM will loop through the enclosed array, outputting the (sub-)format each turn
339 and substituting the placeholder with the current element.\& This example includes
340 a newline character, which will result in one filename per line.\&
341 .PP
342 Multiple arrays may be placed into a single iterator.\& RPM will then iterate over
343 all of them in lockstep, meaning that the first iteration will substitute each
344 placeholder with its array'\&s first element, the second iteration will use each
345 array'\&s second element, and so on.\& For example:
346 .PP
347 .nf
348 .RS 4
349 [%10{FILESIZES} %{FILENAMES}\\n]
350 .fi
351 .RE
352 .PP
353 This is useful with \fIparallel\fR arrays that RPM keeps internally.\& These are sets
354 of arrays where all elements at the same index correspond to each other.\& One can
355 think of parallel arrays as table columns that can be arbitrarily rearranged.\&
356 The above example will output a table of files and their sizes.\&
357 .PP
358 Sometimes, it is useful to combine an array with one or more scalars in the same
359 iterator.\& This is possible since RPM internally treats all scalars as arrays of
360 size one.\& However, iterators may only contain arrays of the same size, otherwise
361 RPM will complain.\& To avoid that, you can "lock" an array so that only its first
362 element is used in each iteration, by prefixing the tag with the equal sign, for
363 example:
364 .PP
365 .nf
366 .RS 4
367 [%{=NAME} %{FILENAMES}\\n]
368 .fi
369 .RE
370 .PP
371 This will produce an "annotated" file list where each filename is preceded by
372 the name of the package that contains it.\&
373 .PP
374 .SS Expressions
375 .PP
376 Simple conditionals may be evaluated through query \fIexpressions\fR in the form of
377 .PP
378 .nf
379 .RS 4
380 %|EXPR|
381 .fi
382 .RE
383 .PP
384 where \fIEXPR\fR is an expression.\&
385 .PP
386 The only type of expression currently supported is a C-like ternary operator for
387 simple if/then/else conditions, which has the syntax
388 .PP
389 .nf
390 .RS 4
391 %|TAG?{PRESENT}:{ABSENT}|
392 .fi
393 .RE
394 .PP
395 where \fIPRESENT\fR and \fIABSENT\fR are query formats that should be expanded if the
396 queried package does and doesn'\&t have the \fITAG\fR, respectively.\& Thus, expressions
397 can be nested.\&
398 .PP
399 .SH EXAMPLES
400 .SS Example 1. Query commands
401 .PP
402 \fBrpm -qa --queryformat "%-30{NAME} %{SIZE:humaniec}\en"\fR
403 .RS 4
404 Print a table of all installed package names and their human-readable
405 sizes.\&
406 .PP
407 .RE
408 \fBrpm -q --queryformat "%{NAME} %{INSTALLTIME:date}\en" fileutils\fR
409 .RS 4
410 Print the \fBfileutils\fR package name followed by its installation date.\&
411 .PP
412 .RE
413 \fBrpm -q --queryformat "[%{FILEMODES:perms} %{FILENAMES}\en]" rpm\fR
414 .RS 4
415 Print all filenames owned by the \fBrpm\fR package, one per line, with each
416 name preceded by a file permissions string similar to the long listing
417 format of \fBls\fR(1).\&
418 .PP
419 .RE
420 \fBrpm -q --queryformat "[%{REQUIRENAME} %{REQUIREFLAGS:depflags}
421 %{REQUIREVERSION}\en]" vlock\fR
422 .RS 4
423 Print all capabilities on which the \fBvlock\fR package depends in the form
424 of version comparisons, one per line, with the capability name and the
425 required version as the left and right operand, respectively.\&
426 .PP
427 .RE
428 \fBrpm -qa --queryformat "%-30{NAME} %|PREINPROG?\&{ %{PREINPROG}}:{ no}|\en"\fR
429 .RS 4
430 Print a table of all installed package names in the left column and the
431 program names used for their \fBprein\fR scriptlets (such as the default
432 \fB/bin/sh\fR) in the right column, with the latter being \fBno\fR if the given
433 package has no \fBprein\fR scriptlet.\&
434 .PP
435 .RE
436 .SS Example 2. Command aliases
437 .PP
438 \fI/usr/lib/rpm/rpmpopt-VERSION\fR
439 .RS 4
440 A \fBpopt\fR(3) alias file used by \fBrpm\fR(8) itself to implement various
441 shorthand options (such as \fB--scripts\fR) with the help of query formats.\&
442 Replace \fIVERSION\fR with the version of RPM installed on your system.\&
443 .PP
444 .RE
445 .SS Example 3. Runtime scriptlets
446 .PP
447 Print the exact file list of a package after its installation:
448 .PP
449 .nf
450 .RS 4
451 %post -q
452 for f in [%%{instfilenames} ]; do
453 echo $f
454 done
455 .fi
456 .RE
457 .PP
458 Note that the trailing space inside the square brackets is required in order for
459 the query format to be expanded to separate words that the \fBfor\fR statement can
460 loop over.\&
461 .PP
462 See the scriptlet expansion documentation in \fBSEE ALSO\fR for more details, and
463 \fBrpm-spec\fR(5) for more information on scriptlets in general.\&
464 .PP
465 .SH SEE ALSO
466 .PP
467 \fBrpm\fR(8), \fBrpm-common\fR(8), \fBrpm-config\fR(5), \fBrpm-spec\fR(5), \fBpopt\fR(3)
468 .PP
469 \fBhttps://rpm.\&org/docs/latest/manual/tags\fR
470 .br
471 \fBhttps://rpm.\&org/docs/latest/manual/scriptlet_expansion\fR