lsplt::v2 Namespace Reference

Data Structures
struct	MapInfo
	An entry that describes a line in /proc/self/maps. You can obtain a list of these entries by calling Scan(). More...

Functions
bool	RegisterHook (dev_t dev, ino_t inode, std::string_view symbol, void *callback, void **backup)
	Register a hook to a function by inode. For so within an archive, you should use #RegisterHook(ino_t, uintptr_t, size_t, std::string_view, void *, void **) instead. More...
bool	RegisterHook (dev_t dev, ino_t inode, uintptr_t offset, size_t size, std::string_view symbol, void *callback, void **backup)
	Register a hook to a function by inode with offset range. This is useful when hooking a library that is directly loaded from an archive without extraction. More...
bool	CommitHook ()
	Commit all registered hooks. More...
bool	InvalidateBackup ()
	Invalidate backup memory regions Normally LSPlt will backup the hooked memory region and do hook on a copied anonymous memory region, and restore the original memory region when the hook is unregistered (when the callback of RegisterHook() is the original function). This function will restore the backup memory region and do all existing hooks on the original memory region. More...

Function Documentation

CommitHook()

bool lsplt::v2::CommitHook

(

)

Commit all registered hooks.

Returns

Whether all hooks are successfully committed. If any of the hooks fail to commit, the result is false.

Note

This function is thread-safe.

The return value indicates whether all hooks are successfully committed. You can determine which hook fails by checking the backup function pointer of RegisterHook().

See also

RegisterHook()

InvalidateBackup()

bool lsplt::v2::InvalidateBackup

(

)

Invalidate backup memory regions Normally LSPlt will backup the hooked memory region and do hook on a copied anonymous memory region, and restore the original memory region when the hook is unregistered (when the callback of RegisterHook() is the original function). This function will restore the backup memory region and do all existing hooks on the original memory region.

Returns

Whether all hooks are successfully invalidated. If any of the hooks fail to invalidate, the result is false.

Note

This function is thread-safe.

This will be automatically called when the library is unloaded.

See also

RegisterHook()

RegisterHook() [1/2]

bool lsplt::v2::RegisterHook	(	dev_t	dev,
		ino_t	inode,
		std::string_view	symbol,
		void *	callback,
		void **	backup
	)

Register a hook to a function by inode. For so within an archive, you should use #RegisterHook(ino_t, uintptr_t, size_t, std::string_view, void *, void **) instead.

Parameters

[in]	dev	The device number of the memory region.
[in]	inode	The inode of the library to hook. You can obtain the inode by #stat() or by finding the library in the list returned by #lsplt::v1::MapInfo::Scan().
[in]	symbol	The function symbol to hook.
[in]	callback	The callback function pointer to call when the function is called.
[out]	backup	The backup function pointer which can call the original function. This is optional.

Returns

Whether the hook is successfully registered.

Note

This function is thread-safe.

backup will not be available until CommitHook() is called.

backup will be nullptr if the hook fails.

You can unhook the function by calling this function with callback set to the backup set by previous call.

LSPlt will backup the hook memory region and restore it when the hook is restored to its original function pointer so that there won't be dirty pages. LSPlt will do hooks on a copied memory region so that the original memory region will not be modified. You can invalidate this behaviour and hook the original memory region by calling InvalidateBackup().

See also

CommitHook()

InvalidateBackup()

RegisterHook() [2/2]

bool lsplt::v2::RegisterHook	(	dev_t	dev,
		ino_t	inode,
		uintptr_t	offset,
		size_t	size,
		std::string_view	symbol,
		void *	callback,
		void **	backup
	)

Register a hook to a function by inode with offset range. This is useful when hooking a library that is directly loaded from an archive without extraction.

Parameters

[in]	dev	The device number of the memory region.
[in]	inode	The inode of the library to hook. You can obtain the inode by #stat() or by finding the library in the list returned by #lsplt::v1::MapInfo::Scan().
[in]	offset	The to the library in the file.
[in]	size	The upper bound size to the library in the file.
[in]	symbol	The function symbol to hook.
[in]	callback	The callback function pointer to call when the function is called.
[out]	backup	The backup function pointer which can call the original function. This is optional.

Returns

Whether the hook is successfully registered.

Note

This function is thread-safe.

backup will not be available until CommitHook() is called.

backup will be nullptr if the hook fails.

You can unhook the function by calling this function with callback set to the backup set by previous call.

LSPlt will backup the hook memory region and restore it when the hook is restored to its original function pointer so that there won't be dirty pages. LSPlt will do hooks on a copied memory region so that the original memory region will not be modified. You can invalidate this behaviour and hook the original memory region by calling InvalidateBackup().

You can get the offset range of the library by getting its entry offset and size in the zip file.

According to the Android linker specification, the offset must be page aligned.

The offset must be accurate, otherwise the hook may fail because the ELF header cannot be found.

The size can be inaccurate but should be larger or equal to the library size, otherwise the hook may fail when the hook pointer is beyond the range.

The behaviour of this function is undefined if offset + size is larger than the the maximum value of size_t.

See also

CommitHook()

InvalidateBackup()