Error looking up function from current process on Linux

[freya022]

Description

JNA seems to be unable to look up functions from the current process, specifically on Linux x64, while the same code works fine on Windows x64 and macOS aarch64. The documentation says JNA should look into the current process if null is passed to Native.load.

Additional details

• The Foreign Function & Memory API from Java 22 finds all functions and all tests succeed

• nm seems to indicate the function is in the shared library, and isn't mangled

  

• The only workaround is to let JNA load the shared library by Native.load("/path/to/libzstd.so", ZstdJna.class)

Repro code

Using the Linux x64 binary found at https://github.com/freya022/discord-zstd-java/actions/runs/18886251057

public interface ZstdJna extends Library {
    ZstdJna INSTANCE = Native.load(null, ZstdJna.class);

    Pointer ZSTD_createDStream();
}

public class Repro {
    public static void main(String[] args) {
        System.load("/path/to/libzstd.so");

        ZstdJna.INSTANCE // Fine
            .ZSTD_createDStream(); // Fails
    }
}

Environment

Java Version: OpenJDK 25+36
JNA Version: 5.18.1 (also tested 4.4.0)
Operating System: Ubuntu 24.04 GitHub Actions runner (image details), also tested on a Kubuntu VM
C/C++ Compiler: GCC 13.3.0

Error

java.lang.UnsatisfiedLinkError: Error looking up function 'ZSTD_createDStream': /usr/lib/jvm/java-25-openjdk-amd64/bin/java: undefined symbol: ZSTD_createDStream
	at com.sun.jna.Function.<init>(Function.java:255)
	at com.sun.jna.NativeLibrary.getFunction(NativeLibrary.java:618)
	at com.sun.jna.NativeLibrary.getFunction(NativeLibrary.java:594)
	at com.sun.jna.NativeLibrary.getFunction(NativeLibrary.java:580)
	at com.sun.jna.Library$Handler.invoke(Library.java:248)
	at jdk.proxy3/jdk.proxy3.$Proxy13.ZSTD_createDStream(Unknown Source)
	at dev.freya02.discord.zstd.jna.ZstdJNATest.test_decompression(ZstdJNATest.java:36)
	at java.base/java.lang.reflect.Method.invoke(Method.java:565)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1604)
	at java.base/java.util.ArrayList.forEach(ArrayList.java:1604)

Workflow details if necessary: https://github.com/freya022/discord-zstd-java/actions/runs/18891473842

[freya022]

I found out that the JDK doesn't set the RTLD_GLOBAL flag when using dlopen, it instead keeps the handles of all libraries loaded by the JVM.
This is why the JDK's foreign function API is able to locate the symbols just fine, it tries to load the function from all the libraries it is aware of.
JNA cannot see them since they weren't loaded globally, and doesn't have access to the JDK's NativeLibraries.

From the the dlopen manual:

If path is NULL, then the returned handle is for the main program.
When given to dlsym, this handle causes a search for a symbol in the main program, followed by all shared objects loaded at program startup, and then all shared objects loaded by dlopen() with the flag RTLD_GLOBAL.

I think all we need to do is update the documentation to mention the behavior difference on Linux systems, as mentioned, being unable to find symbols loaded by System.loadLibrary(String), System.load(String), Runtime.loadLibrary(String) and Runtime.load(String). Not sure if we want to document more even more details about how dlopen and dlsym work.