.\" Generated by scdoc 1.11.4
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "RPM-QUERYFORMAT" "7" "2026-01-08" "RPM 6.0.1"
.PP
.SH NAME
\fBrpm-queryformat\fR - RPM query mini-language
.PP
.SH SYNOPSIS
.SS Query format
[\fIPLACEHOLDER\fR|\fIITERATOR\fR|\fIEXPRESSION\fR|\fITEXT\fR .\&.\&.\&]
.PP
.SS Placeholder
\fB%\fR[\fIWIDTH\fR]\fB{\fR\fITAG\fR[\fB:\fR\fIFORMAT\fR]\fB}\fR
.PP
.SS Iterator
\fB[\fR\fIQUERYFORMAT\fR .\&.\&.\&\fB]\fR
.PP
Note: Square brackets are literal and \fIQUERYFORMAT\fR must contain an array
placeholder.\&
.PP
.SS Expression
\fB%|\fR\fITAG\fR\fB?\&{\fR\fIPRESENT\fR\fB}:{\fR\fIABSENT\fR\fB}|\fR
.PP
Note: Vertical bars are literal, \fIPRESENT\fR and \fIABSENT\fR are query formats.\&
.PP
.SH DESCRIPTION
.PP
RPM supports a simple query language for extracting header data to plain text.\&
Its syntax resembles that of \fBprintf\fR(3) where header tags enclosed in \fB%{\fR and
\fB}\fR, for example \fB%{NAME}\fR, are used as placeholders.\& A string written in this
syntax is called a \fIquery format\fR.\&
.PP
Query formats are currently accepted in the following places:
.PP
.PD 0
.IP 1. 4
Query operations with \fBrpm\fR(8), as a way to control the output (see
\fB--queryformat\fR)
.IP 2. 4
Runtime scriptlets in \fBrpm-spec\fR(5) files, to access arbitrary header data at
runtime
.IP 3. 4
Configuration macros in \fBrpm-config\fR(5) and \fBrpmbuild-config\fR(5), such as
\fB%_query_all_fmt\fR or \fB%_rpmfilename\fR
.PD
.PP
See the \fBEXAMPLES\fR section for more details.\&
.PP
.SH SYNTAX
.PP
A valid query format is composed of optional literal text and zero or more
\fIplaceholders\fR.\& A placeholder has the following syntax:
.PP
.nf
.RS 4
%[WIDTH]{TAG[:FORMAT]}
.fi
.RE
.PP
When RPM produces output according to a query format, it substitutes each
placeholder with the \fITAG\fR data from the queried package and formats the data
according to the specified \fIWIDTH\fR and \fIFORMAT\fR (if given).\& The rest of the
query format is copied to the output unchanged.\&
.PP
Special characters such as \fB\en\fR or \fB\et\fR, with the exception of \fB\e0\fR, are also
supported.\& Curly braces, the percent sign and the backslash may be escaped with
a backslash.\&
.PP
The individual components of a placeholder, as well as some additional language
features, are described in the subsections below.\&
.PP
.SS Tags
.PP
Every RPM package contains a key-value store (the \fIheader\fR) that represents the
package'\&s properties, such as its name, version or file list.\& The keys in this
store are called \fItags\fR, and can be used in a query format as placeholders for
the values (\fIdata\fR) they point to.\& The data is either a single \fIscalar\fR (string,
integer or binary blob), or an \fIarray\fR (argv) of multiple scalars of the same
type.\&
.PP
To obtain a list of all tags supported by the installed version of RPM, run the
following command:
.PP
.nf
.RS 4
rpm -v --querytags
.fi
.RE
.PP
This will print a list of available tags, along with their internal numbers and
types, for example:
.PP
.nf
.RS 4
BASENAMES              1117 argv
BUILDHOST              1007 string
BUILDTIME              1006 int32
DESCRIPTION            1005 i18nstring
EPOCH                  1003 int32
INSTALLTIME            1008 int32
NAME                   1000 string
RELEASE                1002 string
SIZE                   1009 int32
SUMMARY                1004 i18nstring
VERSION                1001 string
.fi
.RE
.PP
Tags are case-insensitive.\& Each tag also has an implicit variant with the
\fBRPMTAG_\fR prefix, such as \fBRPMTAG_NAME\fR.\& Both variants can be used in a query
format interchangeably.\&
.PP
See the tags documentation in \fBSEE ALSO\fR for more details.\&
.PP
.SS Formats
.PP
Each tag is printed in a specific output \fIFORMAT\fR.\& When no format is specified,
the default \fB:string\fR is used which displays a bare-bones representation of the
data.\& You can specify a different format by appending its name after a colon,
for example:
.PP
.nf
.RS 4
%{INSTALLTIME:date}
.fi
.RE
.PP
This is useful for tags that are not stored in human-readable form, such as
sizes, dates or signatures.\& Some formats allow for performing more complex
transformations of the data, such as encoding it in base64 or wrapping it in
JSON syntax.\&
.PP
The following formats are currently available:
.PP
.TS
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx
l lx.
T{
\fBName\fR
T}	T{
\fBDescription\fR
T}
T{
\fB:armor\fR
T}	T{
Wrap a public key in ASCII armor
T}
T{
\fB:arraysize\fR
T}	T{
Display number of elements in array tags
T}
T{
\fB:base64\fR
T}	T{
Encode binary data using base64
T}
T{
\fB:date\fR
T}	T{
Use \fBstrftime\fR(3) "%c" format
T}
T{
\fB:day\fR
T}	T{
Use \fBstrftime\fR(3) "%a %b %d %Y" format
T}
T{
\fB:depflags\fR
T}	T{
Format dependency comparison operator
T}
T{
\fB:deptype\fR
T}	T{
Format dependency type
T}
T{
\fB:expand\fR
T}	T{
Perform macro expansion
T}
T{
\fB:fflags\fR
T}	T{
Format file flags
T}
T{
\fB:fstate\fR
T}	T{
Format file state
T}
T{
\fB:fstatus\fR
T}	T{
Format file verify status
T}
T{
\fB:hashalgo\fR
T}	T{
Display hash algorithm name
T}
T{
\fB:hex\fR
T}	T{
Format in hexadecimal
T}
T{
\fB:octal\fR
T}	T{
Format in octal
T}
T{
\fB:humaniec\fR
T}	T{
Human readable number (in IEC 80000) where K = 1024, M = 1048576, .\&.\&.\&
T}
T{
\fB:humansi\fR
T}	T{
Human readable number (in SI) where K = 1000, M = 1000000, .\&.\&.\&
T}
T{
\fB:json\fR
T}	T{
Wrap data in JSON
T}
T{
\fB:perms\fR
T}	T{
Format file permissions
T}
T{
\fB:pgpsig\fR
T}	T{
Display signature fingerprint and time
T}
T{
\fB:shescape\fR
T}	T{
Escape single quotes for use in a script
T}
T{
\fB:string\fR
T}	T{
Display string format (default)
T}
T{
\fB:tagname\fR
T}	T{
Display tag name
T}
T{
\fB:tagnum\fR
T}	T{
Display tag number
T}
T{
\fB:triggertype\fR
T}	T{
Display trigger suffix
T}
T{
\fB:vflags\fR
T}	T{
Format file verification flags
T}
T{
\fB:xml\fR
T}	T{
Wrap data in simple XML markup
T}
.TE
.sp 1
Note that some formats are type specific, which means they can only be used with
a specific tag type.\& If you attempt to use them with an incompatible type, RPM
will replace them with a placeholder text.\& For example, the following query
format will result in the output "(not a number)":
.PP
.nf
.RS 4
%{NAME:date}
.fi
.RE
.PP
Similarly, if a tag is not present in the queried package, it will be replaced
with the text "(none)".\&
.PP
.SS Width
.PP
You can specify the minimum \fIWIDTH\fR of the data when printed, by placing a
number in between the \fB%\fR and \fB{\fR characters, similarly to field width used in
\fBprintf\fR(3).\& Optionally, prefix the number with the minus sign to left-justify
the text.\&
.PP
.SS Iterators
.PP
Tags pointing to arrays may be expanded to the individual elements by using
\fIiterators\fR.\& An iterator is a query (sub-)format enclosed in square brackets
that contains a placeholder for an array, for example:
.PP
.nf
.RS 4
[%{FILENAMES}\\n]
.fi
.RE
.PP
RPM will loop through the enclosed array, outputting the (sub-)format each turn
and substituting the placeholder with the current element.\& This example includes
a newline character, which will result in one filename per line.\&
.PP
Multiple arrays may be placed into a single iterator.\& RPM will then iterate over
all of them in lockstep, meaning that the first iteration will substitute each
placeholder with its array'\&s first element, the second iteration will use each
array'\&s second element, and so on.\& For example:
.PP
.nf
.RS 4
[%10{FILESIZES} %{FILENAMES}\\n]
.fi
.RE
.PP
This is useful with \fIparallel\fR arrays that RPM keeps internally.\& These are sets
of arrays where all elements at the same index correspond to each other.\& One can
think of parallel arrays as table columns that can be arbitrarily rearranged.\&
The above example will output a table of files and their sizes.\&
.PP
Sometimes, it is useful to combine an array with one or more scalars in the same
iterator.\& This is possible since RPM internally treats all scalars as arrays of
size one.\& However, iterators may only contain arrays of the same size, otherwise
RPM will complain.\& To avoid that, you can "lock" an array so that only its first
element is used in each iteration, by prefixing the tag with the equal sign, for
example:
.PP
.nf
.RS 4
[%{=NAME} %{FILENAMES}\\n]
.fi
.RE
.PP
This will produce an "annotated" file list where each filename is preceded by
the name of the package that contains it.\&
.PP
.SS Expressions
.PP
Simple conditionals may be evaluated through query \fIexpressions\fR in the form of
.PP
.nf
.RS 4
%|EXPR|
.fi
.RE
.PP
where \fIEXPR\fR is an expression.\&
.PP
The only type of expression currently supported is a C-like ternary operator for
simple if/then/else conditions, which has the syntax
.PP
.nf
.RS 4
%|TAG?{PRESENT}:{ABSENT}|
.fi
.RE
.PP
where \fIPRESENT\fR and \fIABSENT\fR are query formats that should be expanded if the
queried package does and doesn'\&t have the \fITAG\fR, respectively.\& Thus, expressions
can be nested.\&
.PP
.SH EXAMPLES
.SS Example 1. Query commands
.PP
\fBrpm -qa --queryformat "%-30{NAME} %{SIZE:humaniec}\en"\fR
.RS 4
Print a table of all installed package names and their human-readable
sizes.\&
.PP
.RE
\fBrpm -q --queryformat "%{NAME} %{INSTALLTIME:date}\en" fileutils\fR
.RS 4
Print the \fBfileutils\fR package name followed by its installation date.\&
.PP
.RE
\fBrpm -q --queryformat "[%{FILEMODES:perms} %{FILENAMES}\en]" rpm\fR
.RS 4
Print all filenames owned by the \fBrpm\fR package, one per line, with each
name preceded by a file permissions string similar to the long listing
format of \fBls\fR(1).\&
.PP
.RE
\fBrpm -q --queryformat "[%{REQUIRENAME} %{REQUIREFLAGS:depflags}
%{REQUIREVERSION}\en]" vlock\fR
.RS 4
Print all capabilities on which the \fBvlock\fR package depends in the form
of version comparisons, one per line, with the capability name and the
required version as the left and right operand, respectively.\&
.PP
.RE
\fBrpm -qa --queryformat "%-30{NAME} %|PREINPROG?\&{ %{PREINPROG}}:{ no}|\en"\fR
.RS 4
Print a table of all installed package names in the left column and the
program names used for their \fBprein\fR scriptlets (such as the default
\fB/bin/sh\fR) in the right column, with the latter being \fBno\fR if the given
package has no \fBprein\fR scriptlet.\&
.PP
.RE
.SS Example 2. Command aliases
.PP
\fI/usr/lib/rpm/rpmpopt-VERSION\fR
.RS 4
A \fBpopt\fR(3) alias file used by \fBrpm\fR(8) itself to implement various
shorthand options (such as \fB--scripts\fR) with the help of query formats.\&
Replace \fIVERSION\fR with the version of RPM installed on your system.\&
.PP
.RE
.SS Example 3. Runtime scriptlets
.PP
Print the exact file list of a package after its installation:
.PP
.nf
.RS 4
%post -q
for f in [%%{instfilenames} ]; do
    echo $f
done
.fi
.RE
.PP
Note that the trailing space inside the square brackets is required in order for
the query format to be expanded to separate words that the \fBfor\fR statement can
loop over.\&
.PP
See the scriptlet expansion documentation in \fBSEE ALSO\fR for more details, and
\fBrpm-spec\fR(5) for more information on scriptlets in general.\&
.PP
.SH SEE ALSO
.PP
\fBrpm\fR(8), \fBrpm-common\fR(8), \fBrpm-config\fR(5), \fBrpm-spec\fR(5), \fBpopt\fR(3)
.PP
\fBhttps://rpm.\&org/docs/latest/manual/tags\fR
.br
\fBhttps://rpm.\&org/docs/latest/manual/scriptlet_expansion\fR