To load a native library, call the static method {@link #loadLibrary} from the static * initializer of the Java class declaring the native methods. The argument should be the library's * short name. * *
For example, if the native code is in libmy_jni_methods.so: * *
{@code
* class MyClass {
* static {
* SoLoader.loadLibrary("my_jni_methods");
* }
* }
* }
*
* Before any library can be loaded SoLoader needs to be initialized. The application using
* SoLoader should do that by calling SoLoader.init early on app initialization path. The call must
* happen before any class using SoLoader in its static initializer is loaded.
*/
@ThreadSafe
public class SoLoader {
/* package */ static final String TAG = "SoLoader";
/* package */ static final boolean DEBUG = false;
/* package */ static final boolean SYSTRACE_LIBRARY_LOADING;
/* package */ @Nullable static SoFileLoader sSoFileLoader;
/**
* locking controlling the list of SoSources. We want to allow long running iterations over the
* list to happen concurrently, but also ensure that nothing modifies the list while others are
* reading it.
*/
private static final ReentrantReadWriteLock sSoSourcesLock = new ReentrantReadWriteLock();
/**
* Ordered list of sources to consult when trying to load a shared library or one of its
* dependencies. {@code null} indicates that SoLoader is uninitialized.
*/
@GuardedBy("sSoSourcesLock")
@Nullable
private static SoSource[] sSoSources = null;
@GuardedBy("sSoSourcesLock")
private static final AtomicInteger sSoSourcesVersion = new AtomicInteger(0);
/** A backup SoSources to try if a lib file is corrupted */
@GuardedBy("sSoSourcesLock")
@Nullable
private static UnpackingSoSource[] sBackupSoSources;
/**
* A SoSource for the Context.ApplicationInfo.nativeLibsDir that can be updated if the application
* moves this directory
*/
@GuardedBy("sSoSourcesLock")
@Nullable
private static ApplicationSoSource sApplicationSoSource;
/** Records the sonames (e.g., "libdistract.so") of shared libraries we've loaded. */
@GuardedBy("SoLoader.class")
private static final HashSet To prevent potential deadlock, always acquire sSoSourcesLock before these locks!
*/
@GuardedBy("SoLoader.class")
private static final Map
* N.B. ONLY FOR TESTS. It has read/write race with {@code
* SoLoader.sSoFileLoader.load(String, int)} in {@link DirectorySoSource#loadLibraryFrom}
*
* @param loader {@link SoFileLoader}
*/
/* package */ static void setSoFileLoader(SoFileLoader loader) {
sSoFileLoader = loader;
}
/** Reset internal status. Only for tests. */
/* package */ static void resetStatus() {
synchronized (SoLoader.class) {
sLoadedLibraries.clear();
sLoadingLibraries.clear();
sSoFileLoader = null;
}
setSoSources(null);
}
}
/**
* Provide a wrapper object for calling {@link System#loadLibrary}. This is useful for controlling
* which ClassLoader libraries are loaded into.
*/
public static void setSystemLoadLibraryWrapper(SystemLoadLibraryWrapper wrapper) {
sSystemLoadLibraryWrapper = wrapper;
}
public static final class WrongAbiError extends UnsatisfiedLinkError {
WrongAbiError(Throwable cause, String machine) {
super(
"APK was built for a different platform. Supported ABIs: "
+ Arrays.toString(SysUtil.getSupportedAbis())
+ " error: "
+ machine);
initCause(cause);
}
}
/**
* Gets the full path of a library.
*
* @param libName the library file name, including the prefix and extension.
* @return the full path of the library, or null if it is not found in none of the SoSources.
* @throws IOException if there is an error calculating the canonical path of libName
*/
public static @Nullable String getLibraryPath(String libName) throws IOException {
String libPath = null;
sSoSourcesLock.readLock().lock();
try {
if (sSoSources != null) {
for (int i = 0; libPath == null && i < sSoSources.length; ++i) {
SoSource currentSource = sSoSources[i];
libPath = currentSource.getLibraryPath(libName);
}
}
} finally {
sSoSourcesLock.readLock().unlock();
}
return libPath;
}
/**
* Gets the dependencies of a library.
*
* @param libName the library file name, including the prefix and extension.
* @return An array naming the dependencies of the library, or null if it is not found in any
* SoSources
* @throws IOException if there is an error reading libName
*/
public static @Nullable String[] getLibraryDependencies(String libName) throws IOException {
String[] deps = null;
sSoSourcesLock.readLock().lock();
try {
if (sSoSources != null) {
for (int i = 0; deps == null && i < sSoSources.length; ++i) {
SoSource currentSource = sSoSources[i];
deps = currentSource.getLibraryDependencies(libName);
}
}
} finally {
sSoSourcesLock.readLock().unlock();
}
return deps;
}
/**
* Returns the so file for the specified library. Returns null if the library does not exist or if
* it's not backed by a file.
*/
public static @Nullable File getSoFile(String shortName) {
String mergedLibName = MergedSoMapping.mapLibName(shortName);
String soName = mergedLibName != null ? mergedLibName : shortName;
String mappedName = System.mapLibraryName(soName);
sSoSourcesLock.readLock().lock();
try {
if (sSoSources != null) {
for (int i = 0; i < sSoSources.length; ++i) {
SoSource currentSource = sSoSources[i];
try {
File soFile = currentSource.getSoFileByName(mappedName);
if (soFile != null) {
return soFile;
}
} catch (IOException e) {
// Failed to get the file, let's skip this so source.
}
}
}
} finally {
sSoSourcesLock.readLock().unlock();
}
return null;
}
public static boolean loadLibrary(String shortName) {
return loadLibrary(shortName, 0);
}
/**
* Load a shared library, initializing any JNI binding it contains.
*
* @param shortName Name of library to find, without "lib" prefix or ".so" suffix
* @param loadFlags Control flags for the loading behavior. See available flags under {@link
* SoSource} (LOAD_FLAG_XXX).
* @return Whether the library was loaded as a result of this call (true), or was already loaded
* through a previous call to SoLoader (false).
*/
public static boolean loadLibrary(String shortName, int loadFlags) throws UnsatisfiedLinkError {
Boolean needsLoad = loadLibraryOnNonAndroid(shortName);
if (needsLoad != null) {
return needsLoad;
}
// This is to account for the fact that we want to load .so files from the apk itself when it is
// a system app.
if ((sAppType == AppType.SYSTEM_APP || sAppType == AppType.UPDATED_SYSTEM_APP)
&& sSystemLoadLibraryWrapper != null) {
sSystemLoadLibraryWrapper.loadLibrary(shortName);
return true;
}
String mergedLibName = MergedSoMapping.mapLibName(shortName);
String soName = mergedLibName != null ? mergedLibName : shortName;
return loadLibraryBySoName(
System.mapLibraryName(soName), shortName, mergedLibName, loadFlags, null);
}
private static @Nullable Boolean loadLibraryOnNonAndroid(String shortName) {
if (sSoSources == null) {
sSoSourcesLock.readLock().lock();
try {
if (sSoSources == null) {
// This should never happen during normal operation,
// but if we're running in a non-Android environment,
// fall back to System.loadLibrary.
if ("http://www.android.com/".equals(System.getProperty("java.vendor.url"))) {
// This will throw.
assertInitialized();
} else {
// Not on an Android system. Ask the JVM to load for us.
synchronized (SoLoader.class) {
boolean needsLoad = !sLoadedLibraries.contains(shortName);
if (needsLoad) {
if (sSystemLoadLibraryWrapper != null) {
sSystemLoadLibraryWrapper.loadLibrary(shortName);
} else {
System.loadLibrary(shortName);
}
}
return needsLoad;
}
}
}
} finally {
sSoSourcesLock.readLock().unlock();
}
}
return null;
}
/* package */ static void loadLibraryBySoName(
String soName, int loadFlags, StrictMode.ThreadPolicy oldPolicy) {
loadLibraryBySoNameImpl(soName, null, null, loadFlags, oldPolicy);
}
private static boolean loadLibraryBySoName(
String soName,
@Nullable String shortName,
@Nullable String mergedLibName,
int loadFlags,
@Nullable StrictMode.ThreadPolicy oldPolicy) {
boolean ret = false;
boolean retry;
do {
retry = false;
try {
ret = loadLibraryBySoNameImpl(soName, shortName, mergedLibName, loadFlags, oldPolicy);
} catch (UnsatisfiedLinkError e) {
final int currentVersion = sSoSourcesVersion.get();
sSoSourcesLock.writeLock().lock();
try {
if (sApplicationSoSource != null && sApplicationSoSource.checkAndMaybeUpdate()) {
Log.w(
TAG,
"sApplicationSoSource updated during load: " + soName + ", attempting load again.");
sSoSourcesVersion.getAndIncrement();
retry = true;
}
} catch (IOException ex) {
throw new RuntimeException(ex);
} finally {
sSoSourcesLock.writeLock().unlock();
}
if (sSoSourcesVersion.get() == currentVersion) {
// nothing changed in soSource, Propagate original error
throw e;
}
}
} while (retry);
return ret;
}
private static boolean loadLibraryBySoNameImpl(
String soName,
@Nullable String shortName,
@Nullable String mergedLibName,
int loadFlags,
@Nullable StrictMode.ThreadPolicy oldPolicy) {
// As an optimization, avoid taking locks if the library has already loaded. Without locks this
// does not provide 100% coverage (e.g. another thread may currently be loading or initializing
// the library), so we'll need to check again with locks held, below.
if (!TextUtils.isEmpty(shortName) && sLoadedAndMergedLibraries.contains(shortName)) {
return false;
}
// LoadingLibLock is used to ensure that doLoadLibraryBySoName and its corresponding JniOnload
// are only executed once per library. It also guarantees that concurrent calls to loadLibrary
// for the same library do not return until both its load and JniOnLoad have completed.
Object loadingLibLock;
boolean loaded = false;
synchronized (SoLoader.class) {
if (sLoadedLibraries.contains(soName)) {
if (mergedLibName == null) {
// Not a merged lib, no need to init
return false;
}
loaded = true;
}
if (sLoadingLibraries.containsKey(soName)) {
loadingLibLock = sLoadingLibraries.get(soName);
} else {
loadingLibLock = new Object();
sLoadingLibraries.put(soName, loadingLibLock);
}
}
// Note that both doLoadLibraryBySoName and invokeJniOnload (below) may re-enter loadLibrary
// (or loadLibraryBySoNameImpl), recursively acquiring additional library and soSource locks.
//
// To avoid bi-directional lock usage (threadA takes loadingLibLock then sSoSourcesLock, threadB
// takes sSoSourcesLock then loadingLibLock) and potential deadlock as this method recursively
// calls loadLibrary, we must acquire sSoSourcesLock first.
sSoSourcesLock.readLock().lock();
try {
synchronized (loadingLibLock) {
if (!loaded) {
synchronized (SoLoader.class) {
if (sLoadedLibraries.contains(soName)) {
// Library was successfully loaded by other thread while we waited
if (mergedLibName == null) {
// Not a merged lib, no need to init
return false;
}
loaded = true;
}
// Else, load was not successful on other thread. We will try in this one.
}
if (!loaded) {
try {
if (Log.isLoggable(TAG, Log.DEBUG)) {
Log.d(TAG, "About to load: " + soName);
}
doLoadLibraryBySoName(soName, loadFlags, oldPolicy);
} catch (UnsatisfiedLinkError ex) {
String message = ex.getMessage();
if (message != null && message.contains("unexpected e_machine:")) {
String machine_msg =
message.substring(message.lastIndexOf("unexpected e_machine:"));
throw new WrongAbiError(ex, machine_msg);
}
throw ex;
}
if (Log.isLoggable(TAG, Log.DEBUG)) {
Log.d(TAG, "Loaded: " + soName);
}
synchronized (SoLoader.class) {
sLoadedLibraries.add(soName);
}
}
}
if ((loadFlags & SOLOADER_SKIP_MERGED_JNI_ONLOAD) == 0) {
// MergedSoMapping#invokeJniOnload does not necessarily handle concurrent nor redundant
// invocation. sLoadedAndMergedLibraries is used in conjunction with loadingLibLock to
// ensure one invocation per library.
boolean isAlreadyMerged =
!TextUtils.isEmpty(shortName) && sLoadedAndMergedLibraries.contains(shortName);
if (mergedLibName != null && !isAlreadyMerged) {
if (SYSTRACE_LIBRARY_LOADING) {
Api18TraceUtils.beginTraceSection("MergedSoMapping.invokeJniOnload[", shortName, "]");
}
try {
if (Log.isLoggable(TAG, Log.DEBUG)) {
Log.d(TAG, "About to merge: " + shortName + " / " + soName);
}
MergedSoMapping.invokeJniOnload(shortName);
sLoadedAndMergedLibraries.add(shortName);
} catch (UnsatisfiedLinkError e) {
// If you are seeing this exception, first make sure your library sets
// allow_jni_merging=True. Trying to merge a library without that
// will trigger this error. If that's already in place, you're probably
// not defining JNI_OnLoad. Calling SoLoader.loadLibrary on a library
// that doesn't define JNI_OnLoad is a no-op when that library is not merged.
// Once you enable merging, it throws an UnsatisfiedLinkError.
// There are three main reasons a library might not define JNI_OnLoad,
// and the solution depends on which case you have.
// - You might be using implicit registration (native methods defined like
// `Java_com_facebook_Foo_bar(JNIEnv* env)`). This is not safe on Android
// https://fb.workplace.com/groups/442333009148653/permalink/651212928260659/
// and is not compatible with FBJNI. Stop doing it. Use FBJNI registerNatives.
// - You might have a C++-only library with no JNI bindings and no static
// initializers with side-effects. You can just delete the loadLibrary call.
// - You might have a C++-only library that needs to be loaded explicitly because
// it has static initializers whose side-effects are needed. In that case,
// pass the SOLOADER_SKIP_MERGED_JNI_ONLOAD flag to loadLibrary.
throw new RuntimeException(
"Failed to call JNI_OnLoad from '"
+ shortName
+ "', which has been merged into '"
+ soName
+ "'. See comment for details.",
e);
} finally {
if (SYSTRACE_LIBRARY_LOADING) {
Api18TraceUtils.endSection();
}
}
}
}
}
} finally {
sSoSourcesLock.readLock().unlock();
}
return !loaded;
}
/**
* Unpack library and its dependencies, returning the location of the unpacked library file. All
* non-system dependencies of the given library will either be on LD_LIBRARY_PATH or will be in
* the same directory as the returned File.
*
* @param shortName Name of library to find, without "lib" prefix or ".so" suffix
* @return Unpacked DSO location
*/
public static File unpackLibraryAndDependencies(String shortName) throws UnsatisfiedLinkError {
assertInitialized();
try {
return unpackLibraryBySoName(System.mapLibraryName(shortName));
} catch (IOException ex) {
throw new RuntimeException(ex);
}
}
private static void doLoadLibraryBySoName(
String soName, int loadFlags, @Nullable StrictMode.ThreadPolicy oldPolicy)
throws UnsatisfiedLinkError {
int result = SoSource.LOAD_RESULT_NOT_FOUND;
sSoSourcesLock.readLock().lock();
try {
if (sSoSources == null) {
Log.e(TAG, "Could not load: " + soName + " because no SO source exists");
throw new UnsatisfiedLinkError("couldn't find DSO to load: " + soName);
}
} finally {
sSoSourcesLock.readLock().unlock();
}
// This way, we set the thread policy only one per loadLibrary no matter how many
// dependencies we load. Each call to StrictMode.allowThreadDiskWrites allocates.
boolean restoreOldPolicy = false;
if (oldPolicy == null) {
oldPolicy = StrictMode.allowThreadDiskReads();
restoreOldPolicy = true;
}
if (SYSTRACE_LIBRARY_LOADING) {
Api18TraceUtils.beginTraceSection("SoLoader.loadLibrary[", soName, "]");
}
Throwable error = null;
try {
sSoSourcesLock.readLock().lock();
try {
for (int i = 0; result == SoSource.LOAD_RESULT_NOT_FOUND && i < sSoSources.length; ++i) {
SoSource currentSource = sSoSources[i];
result = currentSource.loadLibrary(soName, loadFlags, oldPolicy);
if (result == SoSource.LOAD_RESULT_CORRUPTED_LIB_FILE && sBackupSoSources != null) {
// Let's try from the backup source
if (Log.isLoggable(TAG, Log.DEBUG)) {
Log.d(TAG, "Trying backup SoSource for " + soName);
}
for (UnpackingSoSource backupSoSource : sBackupSoSources) {
backupSoSource.prepare(soName);
int resultFromBackup = backupSoSource.loadLibrary(soName, loadFlags, oldPolicy);
if (resultFromBackup == SoSource.LOAD_RESULT_LOADED) {
result = resultFromBackup;
break;
}
}
break;
}
}
} finally {
sSoSourcesLock.readLock().unlock();
}
} catch (Throwable t) {
error = t;
} finally {
if (SYSTRACE_LIBRARY_LOADING) {
Api18TraceUtils.endSection();
}
if (restoreOldPolicy) {
StrictMode.setThreadPolicy(oldPolicy);
}
if (result == SoSource.LOAD_RESULT_NOT_FOUND
|| result == SoSource.LOAD_RESULT_CORRUPTED_LIB_FILE) {
StringBuilder sb = new StringBuilder().append("couldn't find DSO to load: ").append(soName);
if (error != null) {
String cause = error.getMessage();
if (cause == null) {
cause = error.toString();
}
sb.append(" caused by: ").append(cause);
error.printStackTrace();
} else {
// load failure wasn't caused by dependent libraries.
// Print the sources and current native library directory
sSoSourcesLock.readLock().lock();
for (int i = 0; i < sSoSources.length; ++i) {
sb.append("\n\tSoSource ").append(i).append(": ").append(sSoSources[i].toString());
}
if (sApplicationSoSource != null) {
Context updatedContext = sApplicationSoSource.getUpdatedContext();
File updatedNativeLibDir =
ApplicationSoSource.getNativeLibDirFromContext(updatedContext);
sb.append("\n\tNative lib dir: ")
.append(updatedNativeLibDir.getAbsolutePath())
.append("\n");
}
sSoSourcesLock.readLock().unlock();
}
sb.append(" result: ").append(result);
final String message = sb.toString();
Log.e(TAG, message);
UnsatisfiedLinkError err = new UnsatisfiedLinkError(message);
if (error != null) {
err.initCause(error);
}
throw err;
}
}
}
@Nullable
public static String makeNonZipPath(final String localLdLibraryPath) {
if (localLdLibraryPath == null) {
return null;
}
final String[] paths = localLdLibraryPath.split(":");
final ArrayList