BlazeSym is a library that symbolizes addresses where symbol names, source file names, and line numbers can be acquired. It can translate stack traces to function names and their locations in the source code.

• https://github.com/libbpf/blazesym

To build BlazeSym, you must install a Rust environment.

Once successfully installed, you must obtain BlazeSym's source code.

• git clone https://github.com/libbpf/blazesym.git

Next, you would need to go to the root directory of the BlazeSym source code to build BlazeSym.

• cargo build

You may want to build a C header (blazesym.h) to include in your C programs.

• cargo build --features="cheader"

You will see blazesym.h and libblazesym.a in target/debug/ or target/release/ directory. Your C programs, if any, should include blazesym.h and link to libblazesym.a to access functions and various types of BlazeSym.

The following code makes use of BlazeSym to access symbol names, filenames of sources, and line numbers of addresses involved in a process.

	use blazesym::{BlazeSymbolizer, SymbolSrcCfg, SymbolizedResult};

	let process_id: u32 = std::process::id(); // <some process id>
	// load all symbols of loaded files of the given process.
	let sym_srcs = [SymbolSrcCfg::Process { pid: Some(process_id) }];
	let symbolizer = BlazeSymbolizer::new().unwrap();

	let stack: [u64; 2] = [0xff023, 0x17ff93b];			// Addresses of instructions
	let symlist = symbolizer.symbolize(&sym_srcs,		// Pass this configuration every time
	                                   &stack);
	for i in 0..stack.len() {
		let address = stack[i];

		if symlist.len() <= i || symlist[i].len() == 0 {	// Unknown address
			println!("0x{:016x}", address);
			continue;
		}

		let sym_results = &symlist[i];
		if sym_results.len() > 1 {
			// One address may get several results (ex, inline code)
			println!("0x{:016x} ({} entries)", address, sym_results.len());
			
			for result in sym_results {
				let SymbolizedResult {symbol, start_address, path, line_no, column} = result;
				println!("    {}@0x{:016x} {}:{}", symbol, start_address, path, line_no);
			}
		} else {
			let SymbolizedResult {symbol, start_address, path, line_no, column} = &sym_results[0];
			println!("0x{:016x} {}@0x{:016x} {}:{}", address, symbol, start_address, path, line_no);
		}
	}

sym_srcs is a list of symbol sources in a process. However, there is only one SymbolSrcCfg::Process {} here. SymbolSrcCfg::Process {} is a convenient variant for loading all objects, i.e., binaries and shared libraries, mapped in a process. Therefore, developers do not have to specify each object and its base address with SymbolSrcCfg::Process {}.

symlist is a list of lists of SymbolizedResult. The instruction provided at an address can result from several lines of code from multiple functions with optimization. In other words, the result of an address is a list of SymbolizedResult. Each entry in symlist results from the address at the respective position in the argument passed to [BlazeSymbolizer::symbolize()].

SymbolSrcCfg::Kernel {} is a variant to load symbols of the Linux Kernel.

	let sym_srcs = [SymbolSrcCfg::Kernel {
		kallsyms: Some(PathBuf::from("/proc/kallsyms")),
		kernel_image: Some(PathBuf::from("/boot/vmlinux-xxxxx")),
	}];

In this case, you give the path of kallsyms and the path of a kernel image. The path of kallsyms can be that of "/proc/" or a copy of kallsym.

If you are symbolizing against the current running kernel on the same device, give None for both paths. Doing so will find the correct paths for you, if possible. It will use "/proc/kallsyms" for kallsyms and find the kernel image of the running kernel from several potential directories; for instance, "/boot/" and "/usr/lib/debug/boot/".

	let sym_srcs = [SymbolSrcCfg::Kernel { kallsyms: None, kernel_image: None }];

You can still provide a list of ELF files and their base addresses if necessary.

	let sym_srcs = [SymbolSrcCfg::Elf { file_name: PathBuf::from("/lib/libc.so.xxx"),
	                                    base_address: 0x1f005d },
	                SymbolSrcCfg::Elf { fie_name: PathBuf::from("/path/to/my/binary"),
	                                    base_address: 0x77777 },
	                ......
	];

At the base address of an ELF file, its executable segment(s) is loaded.

examples/addr2ln_pid.rs is an example performing symbolization for an address in a process.

	$ ./target/debug/examples/addr2ln_pid 1234 7f0c41ade000
	PID: 1234
	0x7f0c41ade000 wcsxfrm_l@0x7f0c41addd10+752 src/foo.c:0
	$

The above command will display the symbol names, sources' file names, and the line numbers of address 0x7f0c41ade000 in process 1234.

Users should build examples using the following command at the root of the source.

	$ cargo build --examples

The following code symbolizes a list of addresses of a process. It shows the addresses, symbol names, source filenames and line numbers.

	#include "blazesym.h"
	
	struct sym_src_cfg sym_srcs[] = {
		{ SRC_T_PROCESS, .params = { .process { <pid> } } },
	};
	const struct blazesym *symbolizer;
	const struct blazesym_result * result;
	const struct blazesym_csym *sym;
	uint64_t stack[] = { 0x12345, 0x7ff992, ..};
	int stack_sz = sizeof(stack) / sizeof(stack[0]);
	uint64_t addr;
	int i, j;
	
	symbolizer = blazesym_new();
	/* sym_srcs should be passed every time doing symbolization */
	result = blazesym_symbolize(symbolizer,
	                            sym_srcs, 1,
	                            stack, stack_sz);
	
	for (i = 0; i < stack_sz; i++) {
		addr = stack[i];
		
		if (!result || i >= result->size || result->entries[i].size == 0) {
			/* not found */
			printf("[<%016llx>]\n", addr);
			continue;
		}
		
		if (result->entries[i].size == 1) {
			/* found one result */
			sym = &result->entries[i].syms[0];
			printf("[<%016llx>] %s@0x%llx %s:%ld\n", addr, sym->symbol, sym->start_address,
			        sym->path, sym->line_no);
			continue;
		}
		
		/* Found multiple results */
		printf("[<%016llx>] (%d entries)\n", addr, result->entries[i].size);
		for (j = 0; j < result->entries[i].size; j++) {
			sym = &result->entries[i].syms[j];
			printf("    %s@0x$llx %s:%ld\n", sym->symbol, sym->start_address,
			       sym->path, sym->line_no);
		}
	}
	
	blazesym_result_free(result);
	blazesym_free(symbolizer);

struct sym_src_cfg describes a binary, symbol file, shared object, kernel, or process. This example uses a struct sym_src_cfg instance with [blazesym_src_type::SRC_T_PROCESS] type to describe a process. BlazeSym deciphers all the loaded ELF files of the process and loads symbols and DWARF information from them to perform symbolization.

You should include “blazesym.h” in a C program to call BlazeSym. Refer to the “Build” section to generate "blazesym.h".

You also need the following arguments to link against BlazeSym.

	libblazesym.a -lrt -ldl -lpthread -lm

You may want to link a shared library, i.e., libblazesym.so.

[blazesym_src_type::SRC_T_KERNEL] is a variant of struct sym_src_cfg highlighting the kernel as a source of symbolization.

	struct sym_src_cfg sym_srcs[] = {
		{ SRC_T_KERNEL, .params = { .kernel = { .kallsyms = "/proc/kallsyms",
		                                        .kernel_image = "/boot/vmlinux-XXXXX" } } },
	};

You can give kallsyms and kernel_image a NULL. BlazeSym will locate them for the running kernel. For example, by default, kallsyms is at "/proc/kallsyms". Accordingly, the kernel image of the current kernel will be in "/boot/" or "/usr/lib/debug/boot/".

The [blazesym_src_type::SRC_T_ELF] variant of struct sym_src_cfg provides the path of an ELF file and its base address. You can specify a list of ELF files and where they are loaded.

	struct sym_src_cfg sym_srcs[] = {
		{ SRC_T_ELF, .params = { .elf = { .file_name = "/lib/libc.so.xxx",
		                                  .base_address = 0x7fff31000 } } },
		{ SRC_T_ELF, .params = { .elf = { .file_name = "/path/to/a/binary",
		                                  .base_address = 0x1ff329000 } } },
	};

The base address of an ELF file is where its executable segment(s) is loaded.

There is an example of C API in libbpf-bootstrap. You could view it at https://github.com/libbpf/libbpf-bootstrap/blob/master/examples/c/profile.c . This example periodically samples the running process of every processor in a system and prints their stack traces when sampling.