diff --git a/.gitignore b/.gitignore index 7f235865..d9f06796 100644 --- a/.gitignore +++ b/.gitignore @@ -16,3 +16,5 @@ index.tex /site_libs/ /index_files/ /docs/* + +**/*.quarto_ipynb diff --git a/_quarto.yml b/_quarto.yml index f412dbe6..384965d5 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -146,6 +146,7 @@ book: - src/tools/rz-bin/libraries.md - src/tools/rz-bin/strings.md - src/tools/rz-bin/program_sections.md + - src/tools/rz-bin/tables.md - src/tools/rz-diff/intro.md - src/tools/rz-diff/binary_diffing.md - src/tools/rz-asm/intro.md diff --git a/src/tools/rz-bin/tables.md b/src/tools/rz-bin/tables.md new file mode 100644 index 00000000..15bcd42e --- /dev/null +++ b/src/tools/rz-bin/tables.md @@ -0,0 +1,76 @@ +# Table Output and Queries + +Rizin generates tables for certain commands, such as `aflt`, `is`, `izz`, and `il`, when they are executed on a file. These commands return structured data in the form of tables. + +The table output is used to process and display data. Using the table query syntax, users can sort rows, filter (grep) data, select specific columns or rows, paginate results, and limit the output. Tables can also be printed in different output formats such as CSV and JSON, or displayed in various textual layouts, including with borders and headers, with headers only, or without headers. + +## Table Command Syntax + +In Rizin, the help command for the table query syntax is `:?`. + +```text +Usage: +[:[:...]][:] +``` +Note: Table specifiers are applied from left to right. Output format specifiers must be specified at the end. + +Table format specifiers `()`: +``` +| /sort/rev # Sort table by column in reverse order. +| /sortlen/rev # Sort table by column length in reverse order. +| /cols[/[/...]] # Show only specified columns in the table. +| # Show only column (it must not have the same name as an output format specifier). +| /gt/ # Grep rows where column is greater than . +| /ge/ # Grep rows where column is greater than or equal to . +| /lt/ # Grep rows where column is less than . +| /le/ # Grep rows where column is less than or equal to . +| /eq/ # Grep rows where column is equal to . +| /ne/ # Grep rows where column is not equal to . +| /uniq # Only get the first row where column or all columns are unique. +| */page// # Show rows starting from the page number . +| */head/ # Show the first rows. +| */tail/ # Show the last rows. +| /str/ # Grep rows where string is a substring of column . +| /strlen/ # Grep rows where the length of column is . +| /minlen/ # Grep rows where the length of column is greater than . +| /maxlen/ # Grep rows where the length of column is less than . +| /sum/ # Sum all the values of column . +``` +Note: The `/sort` and `/sortlen` commands sort values in increasing order by default. Adding `/rev` reverses the order of the output. + +Example: + +`aflt:nbbs/sort` sorts the results in increasing order of `nbbs` values. + +`aflt:nbbs/sort/rev` sorts the results in decreasing order of `nbbs` values. + +Output format specifiers `()`: +``` +| csv # Print the table in CSV format. +| json # Print the table in JSON format. +| fancy # Print the table in a nice form with borders and headers. +| simple # Print the table in a simple form, only with headers. +| quiet # Print the table in a simple form, without headers. +``` + +--- + +### Example 1: Filter, sort, and format analyzed functions + +Some examples which give a general overview of how to use. + +aflt:addr/cols/name/nbbs:size/gt/32:nbbs/gt/1:nbbs/lt/10:nbbs/sort/rev:fancy +``` +This command selects the `addr`, `name`, and `nbbs` columns. It filters functions whose size is greater than 32 bytes and keeps only those functions whose number of basic blocks (`nbbs`) is greater than 1 and less than 10. The results are displayed in reverse order of nbbs using the fancy table format. + +### Example 2: Paginate strings, filter by length, and export as CSV +``` +izz:string/minlen/8:length/sort/rev:*/page/0/15:csv +``` +This command filters strings whose length is greater than 8 characters and sorts them by length in reverse order. It then paginates the output to show only the first page containing 15 rows and prints the result in CSV format. + +### Example 3: Combine uniqueness, filtering, and JSON output for symbols +``` +is:name/uniq:vaddr/gt/0x1000:name/str/init:addr/sort:json +``` +This command keeps only the first occurrence of each unique symbol name. It filters symbols whose address is greater than `0x1000` and whose name contains the substring `init`. The results are sorted in increasing order.