From bc046fbee02bdc049024bbd9b61ad787def9aa8e Mon Sep 17 00:00:00 2001 From: Farhan Saiyed Date: Fri, 16 Jan 2026 23:01:18 +0530 Subject: [PATCH 1/8] docs: add Table API documentation --- .gitignore | 2 ++ _quarto.yml | 1 + src/tools/rz-bin/tables.md | 69 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 72 insertions(+) create mode 100644 src/tools/rz-bin/tables.md 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..75bec48d --- /dev/null +++ b/src/tools/rz-bin/tables.md @@ -0,0 +1,69 @@ +# Table API + +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 API is used to process and display this data. Using table specifiers, 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 table-based commands 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/ # Sort table by column in increasing or decreasing order. +| /sortlen/ # Sort table length of column in increasing or decreasing 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 . +``` + +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. +``` +Some examples which give a general overview of how to use. + +--- + +### Example 1: Filter, sort, and format analyzed functions + +```text +aflt:addr/cols/name/nbbs:size/gt/32:nbbs/gt/1:nbbs/lt/10:nbbs/sort/dec: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 sorted by nbbs in decreasing order and displayed using the fancy table format. + +### Example 2: Paginate strings, filter by length, and export as CSV +``` +izz:string/minlen/8:length/sort/dec:*/page/0/15:csv +``` +This command filters strings whose length is greater than 8 characters and sorts them by length in decreasing 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:addr/gt/0x1000:name/str/init:addr/sort/inc: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 by address in increasing order and printed in JSON format. \ No newline at end of file From 15e7416df927e69a82df970b01413bc815286979 Mon Sep 17 00:00:00 2001 From: Farhan Saiyed Date: Sat, 17 Jan 2026 12:46:13 +0530 Subject: [PATCH 2/8] removed inc/dec and added rev --- src/tools/rz-bin/tables.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/src/tools/rz-bin/tables.md b/src/tools/rz-bin/tables.md index 75bec48d..f553fe41 100644 --- a/src/tools/rz-bin/tables.md +++ b/src/tools/rz-bin/tables.md @@ -1,12 +1,12 @@ -# Table API +# 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 API is used to process and display this data. Using table specifiers, 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. +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 table-based commands is `:?`. +In Rizin, the help command for the table query syntax is `:?`. ```text Usage: @@ -16,8 +16,8 @@ Note: Table specifiers are applied from left to right. Output format specifiers Table format specifiers `()`: ``` -| /sort/ # Sort table by column in increasing or decreasing order. -| /sortlen/ # Sort table length of column in increasing or decreasing order. +| /sort/ # 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 . @@ -36,6 +36,13 @@ Table format specifiers `()`: | /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 `()`: ``` @@ -51,19 +58,19 @@ Some examples which give a general overview of how to use. ### Example 1: Filter, sort, and format analyzed functions -```text -aflt:addr/cols/name/nbbs:size/gt/32:nbbs/gt/1:nbbs/lt/10:nbbs/sort/dec: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 sorted by nbbs in decreasing order and displayed using the fancy table format. +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/dec:*/page/0/15: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 decreasing order. It then paginates the output to show only the first page containing 15 rows and prints the result in CSV format. +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:addr/gt/0x1000:name/str/init:addr/sort/inc:json +is:name/uniq:addr/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 by address in increasing order and printed in JSON format. \ No newline at end of file +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. \ No newline at end of file From d4fbc5739f2ec388c9c8b83144d07b29daaa2a7d Mon Sep 17 00:00:00 2001 From: Farhan Saiyed Date: Sat, 17 Jan 2026 15:30:40 +0530 Subject: [PATCH 3/8] minor changes --- src/tools/rz-bin/tables.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/tools/rz-bin/tables.md b/src/tools/rz-bin/tables.md index f553fe41..6db8a701 100644 --- a/src/tools/rz-bin/tables.md +++ b/src/tools/rz-bin/tables.md @@ -16,8 +16,8 @@ Note: Table specifiers are applied from left to right. Output format specifiers Table format specifiers `()`: ``` -| /sort/ # Sort table by column in reverse order -| /sortlen/rev # Sort table by column length in reverse order. +| /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 . From be0ea347bc262a6dc2a8bbf3f9e3a3c117ff9b9b Mon Sep 17 00:00:00 2001 From: Farhanhusein Saiyed Date: Tue, 20 Jan 2026 15:27:53 +0530 Subject: [PATCH 4/8] minor changes --- src/tools/rz-bin/tables.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/tools/rz-bin/tables.md b/src/tools/rz-bin/tables.md index 6db8a701..9efc6044 100644 --- a/src/tools/rz-bin/tables.md +++ b/src/tools/rz-bin/tables.md @@ -52,6 +52,7 @@ Output format specifiers `()`: | simple # Print the table in a simple form, only with headers. | quiet # Print the table in a simple form, without headers. ``` + Some examples which give a general overview of how to use. --- @@ -73,4 +74,4 @@ This command filters strings whose length is greater than 8 characters and sorts ``` is:name/uniq:addr/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. \ No newline at end of file +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. From fc8f5c810b573060abd0a3a1e94439e1f09c3aef Mon Sep 17 00:00:00 2001 From: Farhanhusein Saiyed Date: Thu, 22 Jan 2026 12:41:07 +0530 Subject: [PATCH 5/8] Added note on address-based table filters in tables.md Clarified note on address-based table filters and their operation on address types. --- src/tools/rz-bin/tables.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/tools/rz-bin/tables.md b/src/tools/rz-bin/tables.md index 9efc6044..aa7150b2 100644 --- a/src/tools/rz-bin/tables.md +++ b/src/tools/rz-bin/tables.md @@ -53,6 +53,8 @@ Output format specifiers `()`: | quiet # Print the table in a simple form, without headers. ``` +Note: Address-based table filters operate on the address type exposed by the table column. Columns such as `addr` and `vaddr` refer to virtual addresses, while `paddr` refers to physical addresses (file offsets). The table query engine does not perform address translation, therefore table filtering depends on the address type of the selected column. + Some examples which give a general overview of how to use. --- From f0955ecb870b00518efa85bbf0a70e8c0dcc7405 Mon Sep 17 00:00:00 2001 From: Farhanhusein Saiyed Date: Fri, 23 Jan 2026 09:56:11 +0530 Subject: [PATCH 6/8] Update notes on address filters in tables.md Clarified note on address-based table filters and their operation on virtual addresses in examples. --- src/tools/rz-bin/tables.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/tools/rz-bin/tables.md b/src/tools/rz-bin/tables.md index aa7150b2..6eefd174 100644 --- a/src/tools/rz-bin/tables.md +++ b/src/tools/rz-bin/tables.md @@ -53,7 +53,7 @@ Output format specifiers `()`: | quiet # Print the table in a simple form, without headers. ``` -Note: Address-based table filters operate on the address type exposed by the table column. Columns such as `addr` and `vaddr` refer to virtual addresses, while `paddr` refers to physical addresses (file offsets). The table query engine does not perform address translation, therefore table filtering depends on the address type of the selected column. +Note: Address-based table filters operate on the address type exposed by the table column. Columns such as `addr` and `vaddr` refer to virtual addresses, while `paddr` refers to physical addresses (file offsets). Some examples which give a general overview of how to use. @@ -65,6 +65,7 @@ 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. +We are using `addr` for filtering, which means that the filtering is performed on virtual addresses. ### Example 2: Paginate strings, filter by length, and export as CSV ``` @@ -77,3 +78,4 @@ This command filters strings whose length is greater than 8 characters and sorts is:name/uniq:addr/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. +We are using `addr` for filtering, which means that the filtering is performed on virtual addresses. From 0ec475c899807f1e90ad31e1bb859361318483de Mon Sep 17 00:00:00 2001 From: Farhanhusein Saiyed Date: Sun, 25 Jan 2026 21:29:16 +0530 Subject: [PATCH 7/8] Fixed wrong examples --- src/tools/rz-bin/tables.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/tools/rz-bin/tables.md b/src/tools/rz-bin/tables.md index 6eefd174..a65d98cb 100644 --- a/src/tools/rz-bin/tables.md +++ b/src/tools/rz-bin/tables.md @@ -65,7 +65,6 @@ 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. -We are using `addr` for filtering, which means that the filtering is performed on virtual addresses. ### Example 2: Paginate strings, filter by length, and export as CSV ``` @@ -75,7 +74,6 @@ This command filters strings whose length is greater than 8 characters and sorts ### Example 3: Combine uniqueness, filtering, and JSON output for symbols ``` -is:name/uniq:addr/gt/0x1000:name/str/init:addr/sort:json +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. -We are using `addr` for filtering, which means that the filtering is performed on virtual addresses. From 94f4bdcd26d242c4fad2d32a3ae503ae24e3b864 Mon Sep 17 00:00:00 2001 From: Farhan Saiyed Date: Wed, 4 Mar 2026 19:55:46 +0530 Subject: [PATCH 8/8] Fix example Co-authored-by: Rot127 <45763064+Rot127@users.noreply.github.com> --- src/tools/rz-bin/tables.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/src/tools/rz-bin/tables.md b/src/tools/rz-bin/tables.md index a65d98cb..15bcd42e 100644 --- a/src/tools/rz-bin/tables.md +++ b/src/tools/rz-bin/tables.md @@ -53,15 +53,12 @@ Output format specifiers `()`: | quiet # Print the table in a simple form, without headers. ``` -Note: Address-based table filters operate on the address type exposed by the table column. Columns such as `addr` and `vaddr` refer to virtual addresses, while `paddr` refers to physical addresses (file offsets). - -Some examples which give a general overview of how to use. - --- ### 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.