Run and verify object files with llvm-rtdyld-18

You will load an LLVM object file with llvm-rtdyld-18, inspect the functions it sees, verify a linked memory image, and run a selected entry point when execution is appropriate. Allow about 15 minutes if you already have an object file and the LLVM tools installed.

This guide targets the installed Ubuntu LLVM 18.1.3 build. The local manual describes llvm-rtdyld as an LLVM MC-JIT tool. It is a loader and test utility, not a replacement for a normal application linker or runtime.

1. Check the installed command

Confirm which executable will run and record its version:

$ command -v llvm-rtdyld-18
/usr/bin/llvm-rtdyld-18
$ llvm-rtdyld-18 --version
Ubuntu LLVM version 18.1.3
  Optimized build.

Use the versioned command explicitly in scripts when the machine has more than one LLVM release. The available actions are --execute, --printline, --printdebugline, --printobjline and --verify. General help is available with --help; it does not load an input file.

2. Start with a real object file

The input is an object file that LLVM can recognise. For a quick local test, assemble a tiny function with the installed Clang:

$ clang-18 -c -o /tmp/rtdyld-demo.o demo.s
$ file /tmp/rtdyld-demo.o
/tmp/rtdyld-demo.o: ELF 64-bit LSB relocatable, x86-64, ...

Replace /tmp/rtdyld-demo.o with the path to your own object. Keep the source architecture and the RTDyld target aligned. A file that is text, a binary for the wrong target, or an otherwise unsupported object is rejected before loading.

3. List functions without executing them

Use --printline to load and link the object, then print line information for each function:

$ llvm-rtdyld-18 --printline /tmp/rtdyld-demo.o
Function: demo, Size = 0, Addr = 139140502913024

The address is allocated for that invocation, so do not compare it as a stable identifier between runs. The useful result is that the object loaded and the function name was found. In the installed build, a minimal assembly function can report a size of zero even though it is loadable.

--printdebugline loads, links and prints line information using the debug object. --printobjline prints object line information without loading the object first. Choose the latter when you want an inspection that does not allocate the loaded image.

4. Verify the linked image

Run the verifier with an explicit target triple:

$ llvm-rtdyld-18 --verify --triple=x86_64-pc-linux-gnu /tmp/rtdyld-demo.o
$ printf '%s\n' "$?"
0

The manpage lists --triple as the target triple for the disassembler. On this LLVM 18 build it is also required by verify mode. If you omit it, the command stops with -triple required when running in -verify mode, even when the object itself is valid.

Use the triple that matches the object and the environment you are testing. A zero status means this verification run completed successfully. It does not prove that an arbitrary program is safe to execute or that its external runtime dependencies are present.

5. Execute one named entry point

Only do this with object code you trust and intend to run. Pass --execute, select the function with --entry, and put program arguments after --args:

$ llvm-rtdyld-18 --execute --entry=demo /tmp/rtdyld-demo.o --args alpha beta
loaded 'demo' at: 0x77dfe89ba000
$ printf '%s\n' "$?"
7

In this example the function returns 7, so the tool exits with status 7. The loaded address is not stable and should not be parsed by a script. If you omit --entry, this build looks for _main; an object containing only demo fails with no definition for '_main'.

Keep --args at the end of the command and treat its following values as program arguments. Do not use shell text from an untrusted source to construct this command. Quote arguments containing spaces in the normal shell way, and check the resulting status immediately if it controls a test or build step.

6. Add optional inputs deliberately

The RTDyld-specific options let you adjust a test without changing the object. --dylib=<file> adds a library, --mcpu=<cpu-name> targets a specific CPU, and --preallocate=<ulong> allocates memory up front rather than on demand. Use --mcpu=help to ask the installed build for its accepted CPU names.

--check=<file> supplies a file containing RuntimeDyld verifier checks. The local manpage documents the option but does not define the check-file language, so do not invent a format. Use a check file only when you have the matching LLVM test or project documentation for it.

--show-times adds timings for RTDyld phases. This is useful when comparing repeated test runs, but the printed addresses and timing values are run-specific. The --color option controls coloured output and defaults to autodetection.

7. Diagnose failures without changing state

Capture the exit status immediately after the RTDyld command:

llvm-rtdyld-18 --verify --triple=x86_64-pc-linux-gnu /path/to/input.o
status=$?
if [ "$status" -ne 0 ]; then
    printf 'llvm-rtdyld verification failed with status %s\n' "$status" >&2
    exit "$status"
fi

A missing entry point is an object-content problem, not a request for elevated privileges. A bad object path or unreadable file should be checked with ls -l and test -r. There is normally no reason to use sudo: RTDyld reads the input and allocates memory in the current process. Running it as root increases the consequence of executing unsafe code and does not make an incompatible object valid.

When a test has changed state outside the tool, recover that state using the owning build or test system. The commands in this guide do not modify the input object or install anything. If you created a temporary object under /tmp, remove that disposable file only after you have finished inspecting it.