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
TL_APITargets
tl_Targettl_target_name()tl_target_from_name()tl_target_native()tl_target_available()tl_target_is_native()tl_targets()The linker state
tl_Statetl_ErrorFunctl_new()tl_delete()tl_state_target()tl_set_error_func()tl_error_count()Output type
TL_OUTPUT_*tl_set_output_type()tl_get_output_type()tl_get_output_file()tl_set_lib_path()tl_add_library_path()Settings
tl_Flagtl_set_flags()tl_get_flags()tl_StrOpttl_set_str()tl_get_str()tl_MachoPlatformtl_TargetOStl_NumOpttl_set_num()tl_get_num()tl_set_options()tl_parse_args()tl_link_parsed()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()
tl_link_parsed() function
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.