gsym-rs 0.1.5

Install

Use the library from Cargo:

[dependencies]
gsym-rs = "0.1"

Install the command-line tool:

cargo install gsym-rs --locked

This installs gsymtool with ELF/DWARF conversion, memory mapping, and debuginfod discovery enabled.

Read

use gsym::Gsym;

let gsym = Gsym::open("app.gsym")?;
if let Some(symbol) = gsym.lookup(0x401120)? {
    for frame in symbol.frames() {
        println!("{}", String::from_utf8_lossy(frame.name));
    }
}
# Ok::<(), gsym::Error>(())

Write

use gsym::{AddressRange, FileEntry, Function, Gsym, GsymBuilder, LineEntry};

let mut builder = GsymBuilder::new().base_address(0x4000);
let source = builder.add_file(FileEntry::new(b"src", b"main.rs"))?;
builder.add_function(Function {
    lines: vec![LineEntry::new(0x4010, source, 12)],
    ..Function::new(AddressRange::new(0x4010, 0x4020), b"example")
})?;

let bytes = builder.to_bytes()?;
let gsym = Gsym::parse(bytes)?;
let symbol = gsym.lookup(0x4014)?.expect("address is covered");
assert_eq!(symbol.frames()[0].name, b"example");
# Ok::<(), gsym::Error>(())

Convert ELF

# #[cfg(feature = "convert")]
# {
use gsym::convert::ElfConverter;

let report = ElfConverter::default().convert_path("./app")?;
std::fs::write("./app.gsym", report.builder.to_bytes()?)?;
# }
# Ok::<(), gsym::Error>(())

gsymtool convert ./app -o ./app.gsym
gsymtool convert ./app -o ./app.gsym --version v2
gsymtool convert ./app -o ./app.gsym --dwp ./app.dwp
gsymtool convert ./bin --output-dir ./gsym --recursive --jobs 8

Query and inspect

gsymtool lookup ./app.gsym 0x401120 0x40113a
gsymtool dump ./app.gsym --functions
gsymtool verify ./app.gsym
gsymtool transcode ./app.gsym -o ./app-v2.gsym --version v2 --endian big
gsymtool segment ./app-v2.gsym -o ./app-shard.gsym --size 64MiB

lookup accepts the unslid virtual addresses stored in the ELF image. Subtract the load bias from runtime addresses in PIE executables and shared libraries.

Performance

Support

Cargo features

Reader and writer only:

[dependencies]
gsym-rs = { version = "0.1", default-features = false }

License

Licensed under either Apache-2.0 or MIT, at your option.