rpm  5.4.10
queryformat
Go to the documentation of this file.
1 /*! \page queryformat Query formats
2 
3 As it is impossible to please everyone with one style of query output, RPM
4 allows you to specify what information should be printed during a query
5 operation and how it should be formatted.
6 
7 \subsection queryformat_tags Tags
8 
9 All of the information a package contains, apart from signatures and the
10 actual files, is in a part of the package called the header. Each piece
11 of information in the header has a tag associated with it which allows
12 RPM to to tell the difference between the name and description of a
13 package.
14 
15 To get a list of all of the tags your version of RPM knows about, run the
16 command 'rpm --querytags'. It will print out a list like (but much longer
17 then) this:
18 
19 \verbatim
20  RPMTAG_NAME
21  RPMTAG_VERSION
22  RPMTAG_RELEASE
23  RPMTAG_SERIAL
24  RPMTAG_SUMMARY
25  RPMTAG_DESCRIPTION
26  RPMTAG_BUILDTIME
27  RPMTAG_BUILDHOST
28  RPMTAG_INSTALLTIME
29  RPMTAG_SIZE
30 \endverbatim
31 
32 As all of these tags begin with RPMTAG_, you may omit it from query format
33 specifiers and it will be omitted from the rest of this documentation for
34 the same reason.
35 
36 A tag can consist of one element or an array of elements. Each element can
37 be a string or number only.
38 
39 \subsection queryformat_format Query Formats
40 
41 A query format is passed to RPM after the --queryformat argument, and normally
42 should be enclosed in single quotes. This query format is then used to print
43 the information section of a query. This means that when both -i and
44 --queryformat are used in a command, the -i is essentially ignored.
45 Additionally, using --queryformat implies -q, so you may omit the -q as well.
46 
47 The query format is similar to a C style printf string, which the printf(2)
48 man page provides a good introduction to. However, as RPM already knows the
49 type of data that is being printed, you must omit the type specifier. In
50 its place put the tag name you wish to print enclosed in curly braces
51 ({}). For example, the following RPM command prints the names and sizes
52 of all of the packages installed on a system:
53 
54 \verbatim
55  rpm -qa --queryformat "%{NAME} %{SIZE}\n"
56 \endverbatim
57 
58 If you want to use printf formatters, they go between the % and {. To
59 change the above command to print the NAME in the first 30 bytes and
60 right align the size to, use:
61 
62 \verbatim
63  rpm -qa --queryformat "%-30{NAME} %10{SIZE}\n"
64 \endverbatim
65 
66 \subsection queryformat_arrays Arrays
67 
68 RPM uses many parallel arrays internally. For example, file sizes and
69 file names are kept as an array of numbers and an array of strings
70 respectively, with the first element in the size array corresponding
71 to the first element in the name array.
72 
73 To iterate over a set of parallel arrays, enclose the format to be used
74 to print each item in the array within square brackets ([]). For example,
75 to print all of the files and their sizes in the slang-devel package
76 followed by their sizes, with one file per line, use this command:
77 
78 \verbatim
79  rpm -q --queryformat "[%-50{FILENAMES} %10{FILESIZES}\n]" slang-devel
80 \endverbatim
81 
82 Note that since the trailing newline is inside of the square brackets, one
83 newline is printed for each filename.
84 
85 A popular query format to try to construct is one that prints the
86 name of a package and the name of a file it contains on one line,
87 repeated for every file in the package. This query can be very useful
88 for passing information to any program that's line oriented (such as
89 grep or awk). If you try the obvious,
90 
91 \verbatim
92  rpm --queryformat "[%{NAME} %{FILENAMES}\n]" cdp
93 \endverbatim
94 
95 If you try this, you'll see RPM complain about a "parallel array size
96 mismatch". Internally, all items in RPM are actually arrays, so the NAME
97 is a string array containing one element. When you tell RPM to iterate
98 over the NAME and FILENAMES elements, RPM notices the two tags have
99 different numbers of elements and complains.
100 
101 To make this work properly, you need to tell RPM to always print the first
102 item in the NAME element. You do this by placing a '=' before the tag
103 name, like this:
104 
105 \verbatim
106  rpm --queryformat "[%{=NAME} %{FILENAMES}\n]" cdp
107 \endverbatim
108 
109 which will give you the expected output.
110 
111 \verbatim
112  cdp /usr/bin/cdp
113  cdp /usr/bin/cdplay
114  cdp /usr/man/man1/cdp.1
115 \endverbatim
116 
117 \subsection queryformat_formatting Formatting Tags
118 
119 One of the weaknesses with query formats is that it doesn't recognize
120 that the INSTALLTIME tag (for example) should be printed as a date instead
121 of as a number. To compensate, you can specify one of a few different
122 formats to use when printing tags by placing a colon followed the formatting
123 name after the tag name. Here are some examples:
124 
125 \verbatim
126  rpm -q --queryformat "%{NAME} %{INSTALLTIME:date}\n" fileutils
127  rpm -q --queryformat "[%{FILEMODES:perms} %{FILENAMES}\n]" rpm
128  rpm -q --queryformat \
129  "[%{REQUIRENAME} %{REQUIREFLAGS:depflags} %{REQUIREVERSION}\n]" \
130  vlock
131 \endverbatim
132 
133 The :shescape may be used on plain strings to get a string which can pass
134 through a single level of shell and give the original string.
135 
136 \subsection queryformat_expressions Query Expressions
137 
138 Simple conditionals may be evaluated through query expressions. Expressions
139 are delimited by %|...|. The only type of expression currently supported
140 is a C-like ternary conditional, which provides simple if/then/else
141 conditions. For example, the following query format display "present" if
142 the SOMETAG tag is present, and "missing" otherwise:
143 
144 \verbatim
145  %|SOMETAG?{present}:{missing}|
146 \endverbatim
147 
148 Notice that the subformats "present" and "missing" must be inside of curly
149 braces.
150 
151 \subsection queryformat_example Example: Viewing the Verify Flags
152 
153 The following example query is run against dev because I know %verify
154 is used there.
155 \verbatim
156  rpm -q --qf '[%{filenames} %{fileverifyflags}\n]' dev
157 \endverbatim
158 
159 The flags are defined in rpmlib.h (check there for changes):
160 \verbatim
161  #define RPMVERIFY_MD5 (1 << 0)
162  #define RPMVERIFY_FILESIZE (1 << 1)
163  #define RPMVERIFY_LINKTO (1 << 2)
164  #define RPMVERIFY_USER (1 << 3)
165  #define RPMVERIFY_GROUP (1 << 4)
166  #define RPMVERIFY_MTIME (1 << 5)
167  #define RPMVERIFY_MODE (1 << 6)
168  #define RPMVERIFY_RDEV (1 << 7)
169 \endverbatim
170 
171 A 1 bit in the output of the query means the check is enabled.
172 
173 */