Dynamic Library & Globals API

Cross-platform functions for loading shared libraries and accessing exported symbols. More...

Collaboration diagram for Dynamic Library & Globals API:

Functions
c23_nodiscard infix_library_t *	infix_library_open (const char *)
	Opens a dynamic library and returns a handle to it.
void	infix_library_close (infix_library_t *)
	Closes a dynamic library handle.
c23_nodiscard void *	infix_library_get_symbol (infix_library_t *, const char *)
	Retrieves the address of a symbol (function or variable) from a loaded library.
c23_nodiscard infix_status	infix_read_global (infix_library_t *, const char *, const char *, void *, infix_registry_t *)
	Reads the value of a global variable from a library into a buffer.
c23_nodiscard infix_status	infix_write_global (infix_library_t *, const char *, const char *, void *, infix_registry_t *)
	Writes data from a buffer into a global variable in a library.

Detailed Description

Cross-platform functions for loading shared libraries and accessing exported symbols.

Function Documentation

infix_library_close()

void infix_library_close

(

infix_library_t *

lib

)

Closes a dynamic library handle.

Parameters

[in]

lib

The library handle to close. Safe to call with nullptr.

Closes a dynamic library handle.

This is a cross-platform wrapper around FreeLibrary (Windows) and dlclose (POSIX).

Parameters

[in]

lib

The library handle to close. It is safe to call this function with nullptr.

infix_library_get_symbol()

c23_nodiscard void * infix_library_get_symbol	(	infix_library_t *	lib,
		const char *	symbol_name
	)

Retrieves the address of a symbol (function or variable) from a loaded library.

Parameters

[in]	lib	The library handle.
[in]	symbol_name	The name of the symbol to look up.

Returns

A pointer to the symbol's address, or nullptr if not found.

This is a cross-platform wrapper around GetProcAddress (Windows) and dlsym (POSIX).

Note

On POSIX, dlsym returning NULL is not a definitive error condition, as a symbol's address could itself be NULL. The official way to check for an error is to call dlerror() afterwards. This function does not perform that check and does not set the infix error state, as its primary callers (infix_read_global, etc.) will set a more specific INFIX_CODE_SYMBOL_NOT_FOUND error if the lookup fails.

Parameters

[in]	lib	The library handle.
[in]	symbol_name	The name of the symbol to look up (e.g., "my_function").

Returns

A void* pointer to the symbol's address, or nullptr if not found.

infix_library_open()

c23_nodiscard infix_library_t * infix_library_open

(

const char *

path

)

Opens a dynamic library and returns a handle to it.

Parameters

[in]

path

The file path to the library (e.g., ./mylib.so, user32.dll).

Returns

A handle to the library, or nullptr on failure. The handle must be freed with infix_library_close.

This function is a cross-platform wrapper around LoadLibraryA (Windows) and dlopen (POSIX). On failure, it sets the thread-local error state with detailed system-specific information using _infix_set_system_error.

Parameters

[in]

path

The file path to the library (e.g., "./mylib.so", "user32.dll").

Returns

A pointer to an infix_library_t handle on success, or nullptr on failure. The returned handle must be freed with infix_library_close.

infix_read_global()

c23_nodiscard infix_status infix_read_global	(	infix_library_t *	lib,
		const char *	symbol_name,
		const char *	type_signature,
		void *	buffer,
		infix_registry_t *	registry
	)

Reads the value of a global variable from a library into a buffer.

Uses the signature parser to determine the size of the variable to ensure the correct number of bytes are copied.

Parameters

[in]	lib	The library handle.
[in]	symbol_name	The name of the global variable.
[in]	type_signature	The infix signature string describing the variable's type.
[out]	buffer	A pointer to the destination buffer to receive the data.
[in]	registry	An optional registry for resolving named types in the signature.

Returns

INFIX_SUCCESS on success, or an error code on failure.

Reads the value of a global variable from a library into a buffer.

This function first looks up the symbol's address. It then uses the infix signature parser (infix_type_from_signature) to determine the size of the variable. This ensures that the correct number of bytes are copied from the library's data segment into the user's buffer, preventing buffer overflows.

Parameters

[in]	lib	The library handle.
[in]	symbol_name	The name of the global variable.
[in]	type_signature	The infix signature string describing the variable's type (e.g., "int32", "{double,double}").
[out]	buffer	A pointer to the destination buffer to receive the data. This buffer must be large enough to hold the type described by the signature.
[in]	registry	An optional registry for resolving named types in the signature.

Returns

INFIX_SUCCESS on success, or an error code on failure (e.g., symbol not found, invalid signature).

infix_write_global()

c23_nodiscard infix_status infix_write_global	(	infix_library_t *	lib,
		const char *	symbol_name,
		const char *	type_signature,
		void *	buffer,
		infix_registry_t *	registry
	)

Writes data from a buffer into a global variable in a library.

Parameters

[in]	lib	The library handle.
[in]	symbol_name	The name of the global variable.
[in]	type_signature	The infix signature string describing the variable's type.
[in]	buffer	A pointer to the source buffer containing the data to write.
[in]	registry	An optional registry for resolving named types in the signature.

Returns

INFIX_SUCCESS on success, or an error code on failure.

Writes data from a buffer into a global variable in a library.

This function is analogous to infix_read_global. It finds the symbol's address and uses the signature string to determine the correct number of bytes to copy from the source buffer to the library's memory.

Note

This operation assumes that the memory page containing the global variable is writable. This is typical for .data or .bss segments but may fail if the variable is in a read-only segment (e.g., a const global). The function does not attempt to change memory permissions.

Parameters

[in]	lib	The library handle.
[in]	symbol_name	The name of the global variable.
[in]	type_signature	The infix signature string describing the variable's type.
[in]	buffer	A pointer to the source buffer containing the data to write.
[in]	registry	An optional registry for resolving named types in the signature.

Returns

INFIX_SUCCESS on success, or an error code on failure.