| # llvm-gsymutil - GSYM dumping, searching and creating utility |
| |
| ```{program} llvm-gsymutil |
| ``` |
| |
| ## SYNOPSIS |
| |
| {program}`llvm-gsymutil` \[*options*\] \[*gsym-files...*\] |
| |
| ## DESCRIPTION |
| |
| {program}`llvm-gsymutil` is a tool for dumping, searching, and creating GSYM |
| files. |
| |
| GSYM is a compact file format for debug information, optimized for fast |
| lookups. It can represent address ranges, line tables, and inline info. |
| |
| The tool has three main modes of operation: |
| |
| 1. **Dump Mode**: If one or more GSYM files are specified as arguments without |
| any lookup options, the tool dumps all the information contained in the |
| specified files. |
| 2. **Lookup Mode**: If a single GSYM file is specified along with one or more |
| {option}`--address` options (or {option}`--addresses-from-stdin`), the tool |
| performs lookups for the specified addresses in the GSYM file. |
| 3. **Convert Mode**: If the {option}`--convert` option is specified, the tool |
| converts the specified ELF or Mach-O file into GSYM format. |
| |
| ## OPTIONS |
| |
| :::{option} --help, -h |
| Display information on the various flags. |
| ::: |
| |
| :::{option} --version, -v |
| Display the version of the tool. |
| ::: |
| |
| :::{option} --verbose |
| Enable verbose logging and encoding details. |
| ::: |
| |
| :::{option} --convert=<file> |
| Convert the specified file to the GSYM format. Supported files include ELF and |
| Mach-O files. The tool will convert their debug info (DWARF) and symbol table. |
| ::: |
| |
| :::{option} --symtab-file=<file> |
| Specify a separate file to read the symbol table from during GSYM conversion. |
| Use when the symbol table and debug info are in separate files. Matching |
| architectures are selected automatically for universal binaries. |
| ::: |
| |
| :::{option} --merged-functions |
| - When used with {option}`--convert`, encodes merged function information for |
| functions in debug info that have matching address ranges. Without this |
| option, one function per unique address range will be emitted. |
| - When used with {option}`--address` or {option}`--addresses-from-stdin`, all |
| merged functions for a particular address will be displayed. Without this |
| option, only one function will be displayed. |
| ::: |
| |
| :::{option} --dwarf-callsites |
| Load call site info from DWARF, if available. This flag only has an impact |
| when converting to gsym. When using llvm-gsymutil to lookup addresses, |
| any callsite information will automatically be displayed without this flag. |
| ::: |
| |
| :::{option} --arch=<arch> |
| Process debug information for the specified CPU architecture only. |
| Architectures may be specified by name or by number. This option can be |
| specified multiple times, once for each desired architecture. |
| ::: |
| |
| :::{option} --out-file=<file>, -o <file> |
| Specify the path where the converted GSYM file will be saved. When not |
| specified, a '.gsym' extension will be appended to the file name specified in |
| the {option}`--convert` option. |
| ::: |
| |
| :::{option} --verify |
| Verify the generated GSYM file against the information in the file that was |
| converted. |
| ::: |
| |
| :::{option} --num-threads=<n> |
| Specify the maximum number (n) of simultaneous threads to use when converting |
| files to GSYM. Defaults to the number of cores on the current machine. |
| ::: |
| |
| :::{option} --segment-size=<size> |
| Specify the size in bytes of the size the final GSYM file should be segmented |
| into. This allows GSYM files to be split across multiple files. |
| ::: |
| |
| :::{option} --quiet |
| Do not output warnings about the debug information. |
| ::: |
| |
| :::{option} --address=<addr> |
| Lookup an address in a GSYM file. Can be specified multiple times. |
| ::: |
| |
| :::{option} --addresses-from-stdin |
| Lookup addresses in a GSYM file that are read from stdin. Each input line is |
| expected to be of the following format: `<addr> <gsym-path>`. |
| ::: |
| |
| :::{option} --json-summary-file=<file> |
| Output a categorized summary of errors into the JSON file specified. |
| ::: |
| |
| :::{option} --merged-functions-filter=<regex> |
| When used with {option}`--address` or {option}`--addresses-from-stdin` and |
| {option}`--merged-functions`, filters the merged functions output to only |
| show functions matching any of the specified regex patterns. Can be |
| specified multiple times. |
| ::: |
| |
| :::{option} --output-version=<version> |
| Set the GSYM output version (1 or 2). Default: 1. |
| ::: |
| |
| :::{option} --statistics[=<format>] |
| Print the size of each section in the input GSYM file(s). Format can be |
| `text` (default), `json`, or `pretty-json`. Calling this option without |
| arguments is equivalent to `--statistics=text`. |
| ::: |
| |
| ## EXAMPLES |
| |
| Convert an ELF file with debug info to GSYM format: |
| |
| ```console |
| $ llvm-gsymutil --convert=input.elf -o input.gsym |
| ``` |
| |
| Lookup addresses in a GSYM file: |
| |
| ```console |
| $ llvm-gsymutil --address=0x400391 --address=0x4004cd input.gsym |
| ``` |
| |
| Lookup addresses from standard input: |
| |
| ```console |
| $ cat addrs.txt |
| 0x400391 input.gsym |
| 0x4004cd input.gsym |
| $ cat addrs.txt | llvm-gsymutil --addresses-from-stdin |
| ``` |
| |
| Dump the contents of a GSYM file: |
| |
| ```console |
| $ llvm-gsymutil input.gsym |
| ``` |
| |
