Home

Awesome

xDL

xDL is an enhanced implementation of the Android DL series functions.

简体中文

Features

Artifacts Size

If xDL is compiled into an independent dynamic library:

ABICompressed (KB)Uncompressed (KB)
armeabi-v7a7.915
arm64-v8a9.120
x869.018
x86_649.120

Usage

1. Add dependency in build.gradle

xDL is published on Maven Central, and uses Prefab package format for native dependencies, which is supported by Android Gradle Plugin 4.0+.

android {
    buildFeatures {
        prefab true
    }
}

dependencies {
    implementation 'io.github.hexhacking:xdl:2.2.0'
}

NOTE:

  1. Starting from version 2.0.0 of xDL, group ID changed from io.hexhacking to io.github.hexhacking.
version rangegroup IDartifact IDRepository URL
[1.0.3, 1.2.1]io.hexhackingxdlrepo
[2.0.0, )io.github.hexhackingxdlrepo
  1. xDL uses the prefab package schema v2, which is configured by default since Android Gradle Plugin 7.1.0. If you are using Android Gradle Plugin earlier than 7.1.0, please add the following configuration to gradle.properties:
android.prefabVersion=2.0.0

2. Add dependency in CMakeLists.txt or Android.mk

CMakeLists.txt

find_package(xdl REQUIRED CONFIG)

add_library(mylib SHARED mylib.c)
target_link_libraries(mylib xdl::xdl)

Android.mk

include $(CLEAR_VARS)
LOCAL_MODULE           := mylib
LOCAL_SRC_FILES        := mylib.c
LOCAL_SHARED_LIBRARIES += xdl
include $(BUILD_SHARED_LIBRARY)

$(call import-module,prefab/xdl)

3. Specify one or more ABI(s) you need

android {
    defaultConfig {
        ndk {
            abiFilters 'armeabi-v7a', 'arm64-v8a', 'x86', 'x86_64'
        }
    }
}

4. Add packaging options

If you are using xDL in an SDK project, you may need to avoid packaging libxdl.so into your AAR, so as not to encounter duplicate libxdl.so file when packaging the app project.

android {
    packagingOptions {
        exclude '**/libxdl.so'
    }
}

On the other hand, if you are using xDL in an APP project, you may need to add some options to deal with conflicts caused by duplicate libxdl.so file.

android {
    packagingOptions {
        pickFirst '**/libxdl.so'
    }
}

There is a sample app in the xdl-sample folder you can refer to.

API

#include "xdl.h"

1. xdl_open() and xdl_close()

#define XDL_DEFAULT           0x00
#define XDL_TRY_FORCE_LOAD    0x01
#define XDL_ALWAYS_FORCE_LOAD 0x02

void *xdl_open(const char *filename, int flags);
void *xdl_open2(struct dl_phdr_info *info);
void *xdl_close(void *handle);

They are very similar to dlopen() and dlclose(). But xdl_open() can bypass the restrictions of Android 7.0+ linker namespace.

Depending on the value of the flags parameter, the behavior of xdl_open() will have some differences:

If xdl_open() really uses dlopen() to load the library, xdl_close() will return the handle from linker (the return value of dlopen()), and then you can decide whether and when to close it with standard dlclose(). Otherwise, NULL will be returned.

filename can be basename or full pathname. However, Android linker has used the namespace mechanism since 7.0. If you pass basename, you need to make sure that no duplicate ELF is loaded into the current process. xdl_open() will only return the first matching ELF. Please consider this fragment of /proc/self/maps on Android 10:

756fc2c000-756fc7c000 r--p 00000000 fd:03 2985  /system/lib64/vndk-sp-29/libc++.so
756fc7c000-756fcee000 --xp 00050000 fd:03 2985  /system/lib64/vndk-sp-29/libc++.so
756fcee000-756fcef000 rw-p 000c2000 fd:03 2985  /system/lib64/vndk-sp-29/libc++.so
756fcef000-756fcf7000 r--p 000c3000 fd:03 2985  /system/lib64/vndk-sp-29/libc++.so
7571fdd000-757202d000 r--p 00000000 07:38 20    /apex/com.android.conscrypt/lib64/libc++.so
757202d000-757209f000 --xp 00050000 07:38 20    /apex/com.android.conscrypt/lib64/libc++.so
757209f000-75720a0000 rw-p 000c2000 07:38 20    /apex/com.android.conscrypt/lib64/libc++.so
75720a0000-75720a8000 r--p 000c3000 07:38 20    /apex/com.android.conscrypt/lib64/libc++.so
760b9df000-760ba2f000 r--p 00000000 fd:03 2441  /system/lib64/libc++.so
760ba2f000-760baa1000 --xp 00050000 fd:03 2441  /system/lib64/libc++.so
760baa1000-760baa2000 rw-p 000c2000 fd:03 2441  /system/lib64/libc++.so
760baa2000-760baaa000 r--p 000c3000 fd:03 2441  /system/lib64/libc++.so

xdl_open2() creates a handle from struct dl_phdr_info. xdl_open2() is always XDL_DEFAULT semantics, i.e. it will not try to load ELF with dlopen().

2. xdl_sym() and xdl_dsym()

void *xdl_sym(void *handle, const char *symbol, size_t *symbol_size);
void *xdl_dsym(void *handle, const char *symbol, size_t *symbol_size);

They are very similar to dlsym(). They all takes a "handle" of an ELF returned by xdl_open() and the null-terminated symbol name, returning the address where that symbol is loaded into memory.

If the symbol_size parameter is not NULL, it will be assigned as "the bytes occupied by the content corresponding to the symbol in the ELF". If you don't need this information, just pass NULL.

xdl_sym() lookup "dynamic link symbols" in .dynsym as dlsym() does.

xdl_dsym() lookup "debuging symbols" in .symtab and ".symtab in .gnu_debugdata".

Notice:

3. xdl_addr()

typedef struct
{
    const char       *dli_fname;
    void             *dli_fbase;
    const char       *dli_sname;
    void             *dli_saddr;
    size_t            dli_ssize;
    const ElfW(Phdr) *dlpi_phdr;
    size_t            dlpi_phnum;
} xdl_info_t;

#define XDL_DEFAULT 0x00
#define XDL_NON_SYM 0x01

int xdl_addr(void *addr, xdl_info_t *info, void **cache);
int xdl_addr4(void *addr, xdl_info_t *info, void **cache, int flags);
void xdl_addr_clean(void **cache);

xdl_addr() is similar to dladdr(). But there are a few differences:

void *cache = NULL;
xdl_info_t info;
xdl_addr(addr_1, &info, &cache);
xdl_addr(addr_2, &info, &cache);
xdl_addr(addr_3, &info, &cache);
xdl_addr_clean(&cache);

4. xdl_iterate_phdr()

#define XDL_DEFAULT       0x00
#define XDL_FULL_PATHNAME 0x01

int xdl_iterate_phdr(int (*callback)(struct dl_phdr_info *, size_t, void *), void *data, int flags);

xdl_iterate_phdr() is similar to dl_iterate_phdr(). But xdl_iterate_phdr() is compatible with android 4.x on ARM32, and always including linker / linker64.

xdl_iterate_phdr() has an additional "flags" parameter, one or more flags can be bitwise-or'd in it:

These flags are needed because these capabilities require additional execution time, and you don't always need them.

5. xdl_info()

#define XDL_DI_DLINFO 1  // type of info: xdl_info_t

int xdl_info(void *handle, int request, void *info);

xdl_info() is similar to dlinfo(). xdl_info() obtains information about the dynamically loaded object referred to by handle (obtained by an earlier call to xdl_open).

The only request parameter currently supported is XDL_DI_DLINFO, which means to return data of type xdl_info_t through the info parameter (note that the values of dli_sname, dli_saddr, dli_ssize in the returned xdl_info_t at this time both are 0).

On success, xdl_info() returns 0. On failure, it returns -1.

Support

Contributing

License

xDL is MIT licensed, as found in the LICENSE file.

History

xCrash 2.x contains a very rudimentary module xc_dl for searching system library symbols, which has many problems in performance and compatibility. xCrash 2.x uses it to search a few symbols from libart, libc and libc++.

Later, some other projects began to use the xc_dl module alone, including in some performance-sensitive usage scenarios. At this time, we began to realize that we need to rewrite this module, and we need a better implementation.