tinylinkerAPI referenceGet source

tinylinker reads ELF/PE/Mach-O objects, static archives, shared libraries and GNU ld scripts, and writes an executable, a shared library, or a relocatable object. It can also link straight into memory, which is what a compiler runtime wants for JIT-style execution.

Every supported (architecture, object format) pair is a separate backend compiled into the library; pick one at runtime with tl_new(). A backend is usable for cross-linking on any host; only the backend matching the host can additionally link into memory and run code (see tl_target_is_native).

Everything a caller needs is in this file, and the API page on the documentation site is generated straight out of it: tools/apidoc reads the decorators these comments carry - param, return, see, note, warning, ownership and deprecated, each spelled with a leading at sign - and task apidoc rebuilds the page after any change here.

Index

Linkage

How the entry points below are marked for export, which is the one thing in this header a project may want to decide for itself.

TL_API macro

Marks the entry points that leave the library, which is otherwise compiled with hidden visibility. Define TL_USE_SHARED before including this header when linking against tinylinker as a DLL on Windows.

Note Define it yourself to override the whole scheme, for a build that wants every entry point static or annotated some other way.

Targets

A target is an architecture paired with an object format, and each pair is a separate backend. A build may leave some out, so ask what is there rather than assuming.

tl_Target enum

What a link produces code for. The numbering is part of the ABI: a value read out of a saved configuration still means the same target.

Constant Meaning
TL_TARGET_HOST = 0 The machine this library is running on. tl_new() resolves it to the backend built for this host, and it is the only value for which the result can be relocated into memory and run rather than only written out. Zero, so a calloc’d configuration asks for the host. See tl_target_native()
TL_TARGET_I386_ELF “i386-elf”: 32-bit x86, ELF.
TL_TARGET_X86_64_ELF “x86_64-elf”: 64-bit x86, ELF.
TL_TARGET_ARM_ELF “arm-elf”: 32-bit ARM, ELF, hard float.
TL_TARGET_ARM64_ELF “arm64-elf”: AArch64, ELF.
TL_TARGET_RISCV64_ELF “riscv64-elf”: 64-bit RISC-V, ELF.
TL_TARGET_I386_PE “i386-pe”: 32-bit x86, Windows PE.
TL_TARGET_X86_64_PE “x86_64-pe”: 64-bit x86, Windows PE.
TL_TARGET_ARM64_PE “arm64-pe”: AArch64, Windows PE.
TL_TARGET_X86_64_MACHO “x86_64-macho”: 64-bit x86, Mach-O.
TL_TARGET_ARM64_MACHO “arm64-macho”: AArch64, Mach-O.
TL_TARGET__COUNT One past the last target; sizes an array.
TL_TARGET_UNKNOWN = TL_TARGET_HOST The name TL_TARGET_HOST had before it said what it meant. Kept as an alias so existing callers still compile; nothing in tinylinker uses it. It comes after TL_TARGET__COUNT because an alias for zero placed any earlier would restart the numbering and move every target. Deprecated Spell it TL_TARGET_HOST. This alias goes away at 1.0.

tl_target_name() function

const char *tl_target_name(tl_Target target);

The name a target is known by on a command line, such as “x86_64-elf”. Answered from a table covering every target, so a name comes back whether or not this build has the backend.

Parameter What it is
target Any value; one outside the enum is an answer, not a crash.

Returns The name, or NULL for TL_TARGET_HOST, TL_TARGET__COUNT and anything out of range.

Ownership Static storage. Never freed, never invalidated.

See also tl_target_from_name()

tl_target_from_name() function

tl_Target tl_target_from_name(const char *name);

Inverse of tl_target_name(). Every target is recognised, not only the ones this build has, so a front end can tell “no such target” from “not compiled in” and say the right thing.

Parameter What it is
name A command-line target name; NULL is accepted and unrecognised.

Returns The target, or TL_TARGET_HOST when the name matches nothing. That sentinel is also a legal request for the host, so a caller validating user input should reject the empty answer before passing it on.

See also tl_target_available()

tl_target_native() function

tl_Target tl_target_native(void);

The target matching the host this library was built for.

Returns That target, or TL_TARGET_HOST if the backend for this host was not compiled in. The two are the same value, so use tl_target_available() to tell them apart.

See also tl_target_is_native()

tl_target_available() function

int32_t tl_target_available(tl_Target target);

Whether this build can link for the target at all. A build may be trimmed down to a handful of backends, so ask before offering one.

Parameter What it is
target The target to look for.

Returns Nonzero if the backend is present, zero otherwise.

tl_target_is_native() function

int32_t tl_target_is_native(tl_Target target);

Whether the target’s output can be relocated into memory and run here, which needs the backend and the host to agree. Everything else can only be written to a file.

Parameter What it is
target The target to ask about.

Returns Nonzero if tl_relocate(), tl_get_symbol() and tl_run() will work for it; zero for a cross target or one this build lacks.

See also tl_relocate()

tl_targets() function

int32_t tl_targets(tl_Target *out, int32_t max);

Fills out with the compiled-in targets.

Parameter What it is
out Where to write them, or NULL to ask for the count alone.
max How many out has room for. Ignored when out is NULL.

Returns How many targets this build has, which may be more than max: counting continues past the buffer, so one call sizes an array and the next fills it. TL_TARGET__COUNT is always big enough.

Note The order is the registry’s, not the enum’s.

The linker state

A link is a state you create, configure, feed and then ask for output. Nothing else in the library carries state between calls.

tl_State typedef

typedef struct tl_State tl_State;

One link in progress: its settings, its inputs, and once relocated the image they produced. Opaque, because the shape differs per backend.

Ownership Created by tl_new(), released by tl_delete(), and never copied: the address is the identity.

Note One state belongs to one thread. Separate states are independent and may be linked concurrently; the library serialises only the reporting of diagnostics between them.

tl_ErrorFunc typedef

typedef void tl_ErrorFunc(void *opaque, const char *msg);

Receives one diagnostic, already formatted and without a trailing newline. Warnings arrive here too, though only errors are counted.

Parameter What it is
opaque Whatever was handed to tl_set_error_func().
msg The text, prefixed with the input being read when there is one.

Ownership msg is freed as soon as the callback returns. Copy it to keep it.

See also tl_set_error_func()

tl_new() function

tl_State *tl_new(tl_Target target);

Creates a linker context.

Parameter What it is
target The target to link for, or TL_TARGET_HOST for this machine.

Returns The context, or NULL if no such backend was built in or memory ran out. The two are not distinguished; tl_target_available() answers the first before you ask.

Ownership Yours. Pass it to tl_delete() exactly once.

See also tl_delete()

tl_delete() function

void tl_delete(tl_State *s);

Releases the context and any image it relocated into memory.

Parameter What it is
s The context, or NULL, so a failed tl_new() needs no test.

Warning Everything the state handed out dies with it: pointers from tl_get_symbol(), strings from tl_get_str() and tl_get_output_file(), and the code an in-memory link mapped. Nothing linked in memory may still be running.

tl_state_target() function

tl_Target tl_state_target(const tl_State *s);

The target this context links for, which tl_new() may have chosen.

Parameter What it is
s The context.

Returns Its target, or TL_TARGET_HOST if s is NULL.

tl_set_error_func() function

void tl_set_error_func(tl_State *s, void *opaque, tl_ErrorFunc *func);

Routes diagnostics to a callback instead of stderr, which is what an embedder with its own error reporting wants.

Parameter What it is
s The context.
opaque Passed back to func untouched; the library never reads it.
func The callback, or NULL to go back to stderr.

Ownership opaque stays the caller’s, and must outlive the state or be cleared before it dies.

See also tl_ErrorFunc

tl_error_count() function

int32_t tl_error_count(const tl_State *s);

How many errors have been reported so far. Nonzero means the output, if one was written at all, is not to be trusted.

Parameter What it is
s The context.

Returns The count. Warnings are not in it, and the linker stops printing after a hundred errors while carrying on counting.

Note tl_relocate() resets it, so read it before relocating rather than after.

Output type

What the link produces. This is the one setting with an ordering rule attached, because choosing it is also what creates the linker’s sections.

TL_OUTPUT_* constants

Constant Meaning
TL_OUTPUT_MEMORY = 1 Link in memory, do not write a file.
TL_OUTPUT_EXE = 2 Executable.
TL_OUTPUT_OBJ = 3 Relocatable object, like ld -r.
TL_OUTPUT_DLL = 4 Shared library, DLL or dylib.

tl_set_output_type() function

int32_t tl_set_output_type(tl_State *s, int32_t output_type);

Selects the output type and creates the linker’s sections.

Parameter What it is
s The context.
output_type One of the TL_OUTPUT_* values.

Returns 0 on success, or a negative value with a diagnostic reported.

Warning Ordering: call this after any option that influences it (-shared, -r, -static, -nostdlib) and before adding any input. The sections do not exist until it returns, and an input added before then has nowhere to land.

See also tl_get_output_type()

tl_get_output_type() function

int32_t tl_get_output_type(tl_State *s);

The output type recorded so far, including one implied by an option such as -shared or -r that a parse has already seen.

Parameter What it is
s The context.

Returns A TL_OUTPUT_* value, or 0 if none has been selected yet.

Note This is how a driver learns what tl_parse_args() decided, so it can hand the answer straight to tl_set_output_type().

tl_get_output_file() function

const char *tl_get_output_file(tl_State *s);

The -o argument seen by tl_parse_args() or tl_set_options(). A driver uses it to name the output without parsing the arguments twice.

Parameter What it is
s The context.

Returns The name, or NULL if no -o was given.

Ownership The state’s. Valid until the setting changes or tl_delete().

tl_set_lib_path() function

void tl_set_lib_path(tl_State *s, const char *path);

Points the linker at the directory holding the target support files, the equivalent of -B. Sets TL_STR_LIB_PATH.

Parameter What it is
s The context.
path The directory. Copied, so the caller’s buffer may go away.

Note This is where the compiler runtime archive is looked for, and where tl_run() finds the runmain shim that turns the program’s exit() into a return rather than the end of the host process.

tl_add_library_path() function

int32_t tl_add_library_path(tl_State *s, const char *pathname);

Appends a directory to search for -l libraries, the equivalent of -L.

Parameter What it is
s The context.
pathname The directory. Copied. Searched after the ones already added, so order is the command line’s.

Returns 0 on success, or a negative value.

See also tl_add_library()

Settings

Everything the linker can be told is reachable as a flag, a string or a number, so an embedder that already has its own command line can translate into these rather than build option strings. The string parser further down is kept for callers who are handed ld-style text, such as -Wl, arguments.

tl_Flag enum

The boolean settings, combined into the bitmask tl_set_flags() takes.

Constant Meaning
TL_F_STATIC = 1u << 0 Do not link against shared libraries.
TL_F_SHARED = 1u << 1 Produce a shared library.
TL_F_RELOCATABLE = 1u << 2 Produce a relocatable object, like -r.
TL_F_RDYNAMIC = 1u << 3 Export all symbols dynamically.
TL_F_SYMBOLIC = 1u << 4 Resolve within this module first.
TL_F_NOSTDLIB = 1u << 5 No startup files or default libraries.
TL_F_NOSTDLIB_PATHS = 1u << 6 Do not search the default library paths.
TL_F_WHOLE_ARCHIVE = 1u << 7 Take every member of following archives.
TL_F_NEW_DTAGS = 1u << 8 Emit DT_RUNPATH rather than DT_RPATH.
TL_F_NODELETE = 1u << 9 Set DF_1_NODELETE.
TL_F_COMMON = 1u << 10 Keep common symbols instead of .bss.
TL_F_UNDERSCORE = 1u << 11 Prefix C symbols with an underscore.
TL_F_BACKTRACE = 1u << 12 Emit the runtime context for backtraces.
TL_F_BOUNDS_CHECK = 1u << 13 Link the bounds checking runtime.

tl_set_flags() function

int32_t tl_set_flags(tl_State *s, uint32_t flags, int32_t on);

Turns the named flags on or off. Flags left out of flags keep the value they had, so settings can be built up in any order.

Parameter What it is
s The context.
flags A tl_Flag bitmask naming which settings to touch.
on Nonzero to set them, zero to clear them.

Returns 0 on success, or a negative value.

Note TL_F_BOUNDS_CHECK implies TL_F_BACKTRACE, and both imply debug information, since neither reads without it.

Warning TL_F_SHARED and TL_F_RELOCATABLE are not switches: each of them also selects an output type, and clearing either one leaves the type at TL_OUTPUT_EXE rather than at whatever it was.

See also tl_get_flags()

tl_get_flags() function

uint32_t tl_get_flags(tl_State *s);

Every flag currently set, as a tl_Flag bitmask, so a state’s switches can be saved and put back.

Parameter What it is
s The context.

Returns The mask. A flag this build compiled out always reads as clear.

tl_StrOpt enum

The settings that carry a string.

Constant Meaning
TL_STR_ENTRY = 1 Entry symbol, as -e.
TL_STR_SONAME DT_SONAME of a shared library.
TL_STR_RPATH Runtime search path.
TL_STR_INTERPRETER ELF interpreter, as –dynamic-linker.
TL_STR_OUTPUT Output file name, as -o.
TL_STR_INIT Symbol to call at load time.
TL_STR_FINI Symbol to call at unload time.
TL_STR_MAPFILE Write a link map here.
TL_STR_INSTALL_NAME Mach-O install name.
TL_STR_LIB_PATH Directory holding the target support files.

tl_set_str() function

int32_t tl_set_str(tl_State *s, tl_StrOpt opt, const char *value);

Sets a string setting.

Parameter What it is
s The context.
opt Which setting.
value The value, copied; NULL clears the setting.

Returns 0 on success, or a negative value with a diagnostic when the setting means nothing to this target, such as TL_STR_INSTALL_NAME anywhere but Mach-O.

See also tl_get_str()

tl_get_str() function

const char *tl_get_str(tl_State *s, tl_StrOpt opt);

The current value of a string setting.

Parameter What it is
s The context.
opt Which setting.

Returns The value, or NULL if it is unset or does not apply here.

Ownership The state’s. Valid until that setting changes or tl_delete().

tl_MachoPlatform enum

The platform a Mach-O image says it was built for, in the LC_BUILD_VERSION the loader reads before it will run the image at all. The numbers are the ones <mach-o/loader.h> gives, so 5 is missing: that is bridgeOS, which nothing links by hand.

Constant Meaning
TL_MACHO_PLATFORM_MACOS = 1 macOS, and the default.
TL_MACHO_PLATFORM_IOS = 2 iOS on a device.
TL_MACHO_PLATFORM_TVOS = 3 tvOS on a device.
TL_MACHO_PLATFORM_WATCHOS = 4 watchOS on a device.
TL_MACHO_PLATFORM_MACCATALYST = 6 An iOS image running on macOS.
TL_MACHO_PLATFORM_IOSSIMULATOR = 7 iOS under the simulator.
TL_MACHO_PLATFORM_TVOSSIMULATOR = 8 tvOS under the simulator.
TL_MACHO_PLATFORM_WATCHOSSIMULATOR = 9 watchOS under the simulator.

See also tl_set_num()

tl_TargetOS enum

Which operating system an ELF image is stamped for. It is orthogonal to the target rather than part of it: the differences are a handful of header bytes, note sections and startup file names, so making it a setting keeps ten targets from becoming forty. PE and Mach-O accept it and ignore it.

Constant Meaning
TL_OS_LINUX = 0 The default, and what an unset state means.
TL_OS_FREEBSD Stamps ELFOSABI_FREEBSD and a .note.tag.
TL_OS_OPENBSD Stamps ELFOSABI_OPENBSD and a .note.openbsd.ident.
TL_OS_NETBSD Stamps ELFOSABI_NETBSD and a .note.netbsd.ident.

See also tl_set_num()

tl_NumOpt enum

The settings that carry a number. Several mean something to one object format only, and the rest ignore them.

Constant Meaning
TL_NUM_TEXT_ADDR = 1 Where .text starts, as -Ttext.
TL_NUM_SECTION_ALIGN Section alignment in the output.
TL_NUM_IMAGE_BASE PE image base.
TL_NUM_STACK_SIZE PE stack reserve.
TL_NUM_SUBSYSTEM PE subsystem.
TL_NUM_COMPAT_VERSION Mach-O compatibility version.
TL_NUM_CURRENT_VERSION Mach-O current version.
TL_NUM_VERBOSE How much to say while working.
TL_NUM_BACKTRACE_DEPTH How many frames a backtrace keeps.
TL_NUM_MACHO_PLATFORM Mach-O platform, one of tl_MachoPlatform.
TL_NUM_MACHO_MINOS Mach-O minimum OS, (major<<16)|(minor<<8)|patch.
TL_NUM_TARGET_OS Which OS the image is for, a tl_TargetOS.
TL_NUM_STRIP Non-zero to leave local symbols out of the image.

tl_set_num() function

int32_t tl_set_num(tl_State *s, tl_NumOpt opt, uint64_t value);

Sets a numeric setting. Everything is passed as 64 bits; narrowing to what the format can hold is the linker’s business, not the caller’s.

Parameter What it is
s The context.
opt Which setting.
value The value, in whatever units that setting counts.

Returns 0 on success, or a negative value with a diagnostic when the setting means nothing to this target or to this build.

See also tl_get_num()

tl_get_num() function

uint64_t tl_get_num(tl_State *s, tl_NumOpt opt);

The current value of a numeric setting, or the linker’s default for it.

Parameter What it is
s The context.
opt Which setting.

Returns The value. A setting this target does not have reads as 0 rather than failing, since there is no value to distinguish it with; use the return of tl_set_num() to find out whether one applies.

tl_set_options() function

int32_t tl_set_options(tl_State *s, const char *options);

Parses a whitespace-separated option string, e.g. “-static -L/usr/lib -Wl,-soname,libfoo.so.1”. Useful when the caller is handed ld-style text; otherwise prefer the typed calls above.

Parameter What it is
s The context.
options The text. Not retained.

Returns 0 on success, or a negative value for an option it cannot parse.

Note Options such as -shared and -r select an output type rather than applying one; read it back with tl_get_output_type() and pass it to tl_set_output_type().

tl_parse_args() function

int32_t tl_parse_args(tl_State *s, int32_t argc, char **argv);

Parses an ld-style argv, skipping argv[0] as in main().

Parameter What it is
s The context.
argc How many entries argv has.
argv The arguments. Not retained.

Returns 0 on success, or a negative value.

Note Input files named on the command line are only queued, not added, so that the output type can still be chosen in between. Nothing is read until tl_link_parsed().

See also tl_link_parsed()

int32_t tl_link_parsed(tl_State *s);

Adds every input file queued by tl_parse_args(), in command-line order.

Parameter What it is
s The context.

Returns 0 on success, or a negative value if any input failed to load.

See also tl_parse_args()

Inputs

Where the linker gets what it links: files on disk, libraries found on the search path, or addresses in this process.

tl_add_file() function

int32_t tl_add_file(tl_State *s, const char *filename);

Adds an input: an object file, a static archive, a shared library, or a GNU ld script. Which one it is comes from the contents, not the name.

Parameter What it is
s The context.
filename The path, used as given; the library search path does not apply here.

Returns 0 on success, or a negative value if the file is missing or is not something this target can read.

Warning Call tl_set_output_type() first. The sections an input lands in do not exist before then.

See also tl_add_library()

tl_add_library() function

int32_t tl_add_library(tl_State *s, const char *libraryname);

Searches the library path for a library by short name, as -l does: “c” finds libc.so or libc.a, and on Windows the import comes from a .dll or a .def rather than an import archive.

Parameter What it is
s The context.
libraryname The name without the “lib” prefix or the extension.

Returns 0 on success, or a negative value if nothing matched.

Note TL_F_STATIC restricts the search to archives.

See also tl_add_library_path()

tl_add_symbol() function

int32_t tl_add_symbol(tl_State *s, const char *name, const void *val);

Defines a symbol that resolves to memory in this process, so that a linked-in image can call back into its host.

Parameter What it is
s The context.
name The C name. TL_F_UNDERSCORE, and the Mach-O convention, are applied here rather than by the caller.
val The address. Not dereferenced, only recorded.

Returns 0 on success, or a negative value.

Warning TL_OUTPUT_MEMORY only: an address in this process means nothing in a file that another process will load.

See also tl_get_symbol()

Building an object in memory

Inputs do not have to come from files. A code generator can hand tinylinker the sections, symbols and relocations it produced and then either write them out as an object or link them together with real files in the same step.

tl_Section typedef

typedef int32_t tl_Section;

A section handle, as returned by tl_add_section(). Zero is never a valid one, which is what lets it double as the failure result.

TL_SEC_* constants

Constant Meaning
TL_SEC_TEXT = 1 Executable.
TL_SEC_RODATA = 2 Read-only data.
TL_SEC_DATA = 3 Writable data.
TL_SEC_BSS = 4 Zero filled, occupies no space in the file.
TL_SEC_DEBUG = 5 Debug information: present in the file, not loaded.
TL_SEC_TDATA = 6 Each thread’s initial copy of its thread-local data.
TL_SEC_TBSS = 7 The same, zero filled, occupying no space in the file.

tl_add_section() function

tl_Section tl_add_section(tl_State *s, const char *name, int32_t kind,
                          int32_t align);

Creates a section, or returns the existing one of that name, so a generator can emit into it in as many pieces as it likes.

Parameter What it is
s The context.
name The section name, or NULL to take the usual one for the kind. TL_SEC_RODATA has no fixed name: the target picks between .rodata and a relro section.
kind One of the TL_SEC_* values. TL_SEC_DEBUG is the one that occupies space in the file and none in the image: a loader never sees it, and a linker will refuse an object that claims otherwise. TL_SEC_TDATA and TL_SEC_TBSS are .tdata and .tbss on ELF, where a symbol defined in them is STT_TLS, and __thread_data and __thread_bss on Mach-O. A Mach-O variable is reached through a descriptor, which the generator writes into a TL_SEC_DATA section named “.thread_vars”. COFF puts both in .tls$, the section the C runtime’s TLS directory gathers between its _tls_start and _tls_end, zero filled for the second.
align Byte alignment. Raises the section’s alignment but never lowers it, so the section ends up as strict as the strictest thing put into it.

Returns The handle, or 0 on failure.

See also tl_section_append()

tl_section_append() function

int64_t tl_section_append(tl_State *s, tl_Section sec, const void *data,
                       size_t len);

Appends bytes to a section.

Parameter What it is
s The context.
sec A handle from tl_add_section().
data The bytes, copied. Ignored for a TL_SEC_BSS section, which takes the space without the contents.
len How many bytes.

Returns The offset they landed at, which is what a later tl_define_symbol() or tl_add_reloc() refers to, or -1 for a handle that is not this state’s. The offset is aligned to the section’s alignment, so it need not be the previous size.

See also tl_define_symbol()

tl_section_zero() function

int64_t tl_section_zero(tl_State *s, tl_Section sec, size_t len);

Appends zero-filled space, for a variable with no initialiser. In TL_SEC_BSS this costs nothing in the output; elsewhere the zeroes are written out.

Parameter What it is
s The context.
sec A handle from tl_add_section().
len How many bytes.

Returns The offset it landed at, or -1 for a handle that is not this state’s.

tl_section_size() function

int64_t tl_section_size(tl_State *s, tl_Section sec);

How much has been appended to a section so far.

Parameter What it is
s The context.
sec A handle from tl_add_section().

Returns The size in bytes, or -1 for a handle that is not this state’s.

TL_SYM_* constants

Constant Meaning
TL_SYM_GLOBAL = 0x01 Visible to other objects, not only this one.
TL_SYM_WEAK = 0x02 A stronger definition elsewhere wins.
TL_SYM_FUNC = 0x04 Code rather than data.

tl_define_symbol() function

int32_t tl_define_symbol(tl_State *s, const char *name, tl_Section sec,
                     uint64_t off, int32_t flags);

Defines a symbol at an offset in a section.

Parameter What it is
s The context.
name The symbol name, spelled exactly as the output should carry it. Unlike tl_add_symbol(), no underscore is added.
sec A handle from tl_add_section().
off Where in that section, usually a tl_section_append() result.
flags TL_SYM_* bits. Neither TL_SYM_GLOBAL nor TL_SYM_WEAK makes the symbol local to this object, and TL_SYM_WEAK wins over TL_SYM_GLOBAL when both are given.

Returns 0 on success, or a negative value.

See also tl_declare_symbol()

tl_declare_symbol() function

int32_t tl_declare_symbol(tl_State *s, const char *name);

Names a symbol this object refers to but does not define, so that the link knows to go looking for it.

Parameter What it is
s The context.
name The symbol name.

Returns 0 on success, or a negative value.

Note tl_add_reloc() declares an unknown symbol by itself, so this is only needed for a reference that no relocation records.

tl_RelocKind enum

What a relocation means, independent of any object format. tinylinker turns these into the target’s own relocation types, and reports the ones an architecture cannot express rather than approximating them.

Constant Meaning
TL_REL_ABS64 = 1 The symbol’s address, 64 bits.
TL_REL_ABS32 The symbol’s address, 32 bits.
TL_REL_PC32 symbol - here, 32 bits.
TL_REL_CALL A call or jump to the symbol.
TL_REL_PAGE21 arm64: the ADRP page of the symbol.
TL_REL_PAGEOFF12 arm64: the low bits, for the paired ADD or LDR.
TL_REL_HI20 riscv: the AUIPC half of a pc-relative address.
TL_REL_LO12_I riscv: the low half, in an I-type instruction.
TL_REL_LO12_S riscv: the low half, in an S-type instruction.
TL_REL_SECREL32 = 10 COFF only, and wanted by CodeView: an address expressed as an offset within its own section, and the index of that section. Debug records are written that way because a debugger reads them before anything has been given a final address.
TL_REL_SECTION = 11 The one-based index of the symbol’s section.
TL_REL_TLS_PAGE21 = 12 A load of the word that locates a thread-local variable. ELF reads it as the initial-exec offset from the thread pointer, through the GOT; Mach-O as the address of the variable’s descriptor.
TL_REL_TLS_PAGEOFF12 = 13 arm64: the low bits, for the paired LDR.
TL_REL_TLS_PC32 = 14 x86-64: a rip-relative MOV of that word.
TL_REL_GOT_PAGE21 = 15 A load of the GOT slot holding a symbol’s address, which is how code reaches one a shared library defines.
TL_REL_GOT_PAGEOFF12 = 16 arm64: the low bits, for the paired LDR.
TL_REL_GOT_PC32 = 17 x86-64: a rip-relative MOV of the slot.
TL_REL_TLS_HI20 = 18 RISC-V’s AUIPC halves of the two loads above. The paired LD takes TL_REL_LO12_I, naming a label on the AUIPC as it does for an address.
TL_REL_GOT_HI20 = 19 riscv: the AUIPC of the GOT slot.
TL_REL_SECREL_HI12 = 20 A thread-local’s offset within the module’s TLS block, which on COFF is its offset within .tls. x86-64 reaches it with TL_REL_SECREL32, and arm64 builds it with a pair of ADDs, the first shifted by twelve.
TL_REL_SECREL_LO12 = 21 arm64: bits 0 to 11 of it.

tl_add_reloc() function

int32_t tl_add_reloc(tl_State *s, tl_Section sec, uint64_t off,
                 const char *sym, tl_RelocKind kind, int64_t addend);

Records that the bytes at off need the address of sym, biased by addend.

Parameter What it is
s The context.
sec A handle from tl_add_section().
off Where in that section the patch goes.
sym The symbol wanted. It does not have to be defined yet; one that is not known is declared undefined here.
kind What the patched bytes should end up holding.
addend Added to the symbol’s address before patching.

Returns 0 on success, or a negative value, including for a kind this architecture has no relocation for.

See also tl_RelocKind

tl_add_section_reloc() function

int32_t tl_add_section_reloc(tl_State *s, tl_Section sec, uint64_t off,
                 tl_Section target, tl_RelocKind kind, int64_t addend);

Records that the bytes at off need the address of another section rather than of a symbol.

DWARF is what wants this. A compile unit refers to its line table, its abbreviations and its strings by an offset from the front of the section holding them, and there is no symbol there to name: the reference is to .debug_line itself. Written as a plain number it is right only while an object holds a single compile unit, because the linker concatenates the debug sections and everything after the first one moves.

What comes out is a relocation against the section: an STT_SECTION symbol on ELF, the section’s own static symbol on COFF, and a relocation with r_extern clear on Mach-O. All three are what a compiler emits for DW_AT_stmt_list.

Parameter What it is
s The context.
sec A handle from tl_add_section(), the section holding the field.
off Where in that section the patch goes.
target A handle from tl_add_section(), the section named.
kind TL_REL_ABS64 or TL_REL_ABS32, and TL_REL_SECREL32 on COFF. A pc-relative or paged kind describes an instruction and is refused.
addend Added to the section’s address before patching, which for a debug reference is the offset within the section named.

Returns 0 on success, or a negative value, including for a handle that names no section and for a kind this format cannot express.

Note For an object, which is what a debug section is written into. In an executable the sections have final addresses and the reference is resolved rather than recorded.

See also tl_add_reloc()

Output

Two ways to finish: write a file, or relocate into this process and call what came out.

tl_output_file() function

int32_t tl_output_file(tl_State *s, const char *filename);

Links everything added so far and writes the result to filename, in the shape tl_set_output_type() chose.

Parameter What it is
s The context.
filename Where to write. Overwritten if it exists.

Returns 0 on success, or a negative value. Check tl_error_count() as well: a diagnostic reported earlier means the output is not to be trusted even if the write itself worked.

See also tl_relocate()

tl_relocate() function

int32_t tl_relocate(tl_State *s);

Links into memory rather than into a file, which is what tl_get_symbol() and tl_run() need first.

Parameter What it is
s The context.

Returns 0 on success, or -1 for a cross target, for a second call on the same state, or for a link that failed.

Ownership The image belongs to the state and is unmapped by tl_delete().

Note It clears the error count on the way in, so a state that reported errors while reading its inputs looks clean afterwards.

Warning Native targets only, since you cannot execute arm64 code on an x86-64 machine. Ask tl_target_is_native() rather than finding out here.

See also tl_get_symbol()

tl_get_symbol() function

void *tl_get_symbol(tl_State *s, const char *name);

The address of a symbol in the in-memory image.

Parameter What it is
s The context.
name The C name; the target’s own spelling, such as the leading underscore Mach-O uses, is applied here.

Returns The address, or NULL if the image has no such symbol. Only meaningful after tl_relocate().

Ownership Points into the state’s image. Dead after tl_delete().

See also tl_relocate()

tl_list_symbols() function

void tl_list_symbols(tl_State *s, void *ctx,
    void (*symbol_cb)(void *ctx, const char *name, const void *val));

Calls symbol_cb once per global symbol of the in-memory image, which is how a host discovers what it just linked without knowing the names.

Parameter What it is
s The context.
ctx Passed back to the callback untouched.
symbol_cb Called with ctx, the symbol’s name and its address. Symbols with no address, and ones another module has no business seeing, are skipped rather than reported.

Ownership The name belongs to the state’s symbol table; copy it to keep it past tl_delete().

See also tl_get_symbol()

tl_run() function

int32_t tl_run(tl_State *s, int32_t argc, char **argv);

Links in memory, then calls main(argc, argv) and returns its exit status. The image stays alive until tl_delete().

Parameter What it is
s The context.
argc How many entries argv has, as main() would see it.
argv The arguments, as main() would see them.

Returns The program’s exit status, or -1 if the link or the lookup failed. A program that exits with -1 is indistinguishable from that.

Warning Without a support library at tl_set_lib_path(), the entry point is called directly, so a program that calls exit() ends the host process rather than returning here.

See also tl_relocate()

tl_version() function

const char *tl_version(void);

The version of the library, as “major.minor.patch”.

Returns The version string.

Ownership Static storage; the same pointer every time.