llvm-gsymutil - GSYM dumping, searching and creating utility

SYNOPSIS

llvm-gsymutil [options] [gsym-files…]

DESCRIPTION

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 --address options (or --addresses-from-stdin), the tool performs lookups for the specified addresses in the GSYM file.

  3. Convert Mode: If the --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= 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= 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 --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 --address or --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= 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=, -o 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 --convert option. :::

:::{option} –verify Verify the generated GSYM file against the information in the file that was converted. :::

:::{option} –num-threads= 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= 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= 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= Output a categorized summary of errors into the JSON file specified. :::

:::{option} –merged-functions-filter= When used with --address or --addresses-from-stdin and --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= Set the GSYM output version (1 or 2). Default: 1. :::

:::{option} –statistics[=] 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:

$ llvm-gsymutil --convert=input.elf -o input.gsym

Lookup addresses in a GSYM file:

$ llvm-gsymutil --address=0x400391 --address=0x4004cd input.gsym

Lookup addresses from standard input:

$ cat addrs.txt
0x400391 input.gsym
0x4004cd input.gsym
$ cat addrs.txt | llvm-gsymutil --addresses-from-stdin

Dump the contents of a GSYM file:

$ llvm-gsymutil input.gsym