home *** CD-ROM | disk | FTP | other *** search
/ Chip 1998 February / CHIP_2_98.iso / misc / src / rpm / docs / queryformat < prev    next >
Text File  |  1997-09-17  |  5KB  |  138 lines
  1. QUERY FORMATS
  2. =============
  3.  
  4. As it is impossible to please everyone with one style of query output, RPM
  5. allows you to specify what information should be printed during a query
  6. operation and how it should be formatted.
  7.  
  8. Tags
  9. ----
  10.  
  11. All of the information a package contains, apart from signatures and the
  12. actual files, is in a part of the package called the header. Each piece
  13. of information in the header has a tag associated with it which allows
  14. RPM to to tell the difference between the name and description of a
  15. package.
  16.  
  17. To get a list of all of the tags your version of RPM knows about, run the
  18. command 'rpm --querytags'. It will print out a list like (but much longer
  19. then) this:
  20.  
  21.     RPMTAG_NAME
  22.     RPMTAG_VERSION
  23.     RPMTAG_RELEASE
  24.     RPMTAG_SERIAL
  25.     RPMTAG_SUMMARY
  26.     RPMTAG_DESCRIPTION
  27.     RPMTAG_BUILDTIME
  28.     RPMTAG_BUILDHOST
  29.     RPMTAG_INSTALLTIME
  30.     RPMTAG_SIZE
  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. Query Formats
  40. -------------
  41.  
  42. A query format is passed to RPM after the --queryformat argument, and normally
  43. should be enclosed in single quotes. This query format is then used to print
  44. the information section of a query. This means that when both -i and 
  45. --queryformat are used in a command, the -i is essentially ignored. 
  46. Additionally, using --queryformat implies -q, so you may omit the -q as well.
  47.  
  48. The query format is similar to a C style printf string, which the printf(2)
  49. man page provides a good introduction to. However, as RPM already knows the
  50. type of data that is being printed, you must omit the type specifier. In
  51. its place put the tag name you with to print enclosed in curly braces
  52. ({}). For example, the following RPM command prints the names and sizes
  53. of all of the packages installed on a system:
  54.  
  55.     rpm -qa --queryformat "%{NAME} %{SIZE}\n"
  56.  
  57. If you want to use printf formatters, they go between the % and {. To
  58. change the above command to print the NAME in the first 30 bytes and
  59. right align the size to, use:
  60.  
  61.     rpm -qa --queryformat "%-30{NAME} %10{SIZE}\n"
  62.  
  63. Arrays
  64. ------
  65.  
  66. RPM uses many parallel arrays internally. For example, file sizes and 
  67. file names are kept as an array of numbers and an array of strings
  68. respectively, with the first element in the size array corresponding
  69. to the first element in the name array. 
  70.  
  71. To iterate over a set of parallel arrays, enclose the format to be used
  72. to print each item in the array within square brackets ([]). For example,
  73. to print all of the files and their sizes in the slang-devel package
  74. followed by their sizes, with one file per line, use this command:
  75.  
  76.     rpm -q --queryformat "[%-50{FILENAMES} %10{FILESIZES}\n]" slang-devel
  77.  
  78. Note that since the trailing newline is inside of the square brackets, one
  79. newline is printed for each filename.
  80.  
  81. A popular query format to try to construct is one that prints the
  82. name of a package and the name of a file it contains on one line, 
  83. repeated for every file in the package. This query can be very usefull
  84. for passing information to any program that's line oriented (such as
  85. grep or awk). If you try the obvious,
  86.  
  87.     rpm --queryformat "[%{NAME} %{FILENAMES}\n]" cdp
  88.  
  89. If you try this, you'll see RPM complain about a "parallel array size 
  90. mismatch". Internally, all items in RPM are actually arrays, so the NAME
  91. is a string array containing one element. When you tell RPM to iterate
  92. over the NAME and FILENAMES elements, RPM notices the two tags have 
  93. different numbers of elements and complains.
  94.  
  95. To make this work properly, you need to tell RPM to always print the first
  96. item in the NAME element. You do this by placing a '=' before the tag
  97. name, like this:
  98.  
  99.     rpm --queryformat "[%{=NAME} %{FILENAMES}\n]" cdp
  100.  
  101. which will give you the expected output.
  102.  
  103.     cdp /usr/bin/cdp
  104.     cdp /usr/bin/cdplay
  105.     cdp /usr/man/man1/cdp.1
  106.  
  107. Formatting Tags
  108. ---------------
  109.  
  110. One of the weaknesses with query formats is that it doesn't recognize
  111. that the INSTALLTIME tag (for example) should be printed as a date instead
  112. of as a number. To compensate, you can specify one of a few different
  113. formats to use when printing tags by placing a colon followed the formatting 
  114. name after the tag name. Here are some examples:
  115.  
  116.     rpm -q --queryformat "%{NAME} %{INSTALLTIME:date}\n" fileutils
  117.     rpm -q --queryformat "[%{FILEMODES:perms} %{FILENAMES}\n]" rpm
  118.     rpm -q --queryformat \
  119.     "[%{REQUIRENAME} %{REQUIREFLAGS:depflags} %{REQUIREVERSION}\n]" \
  120.     vlock
  121.  
  122. The :shescape may be used on plain strings to get a string which can pass
  123. through a single level of shell and give the original string.
  124.  
  125. Query Expressions
  126. -----------------
  127.  
  128. Simple conditionals may be evaluated through query expressions. Expressions
  129. are delimited by %|...|. The only type of expression currently supported
  130. is a C-like ternary conditional, which provides simple if/then/else
  131. conditions. For example, the following query format display "present" if
  132. the SOMETAG tag is present, and "missing" otherwise:
  133.  
  134.     %|SOMETAG?{present}:{missing}|
  135.  
  136. Notice that the subformats "present" and "missing" must be inside of curly
  137. braces.
  138.