snaums.de - Interface

Catching Native Crashes under JNI with UNIX Signals

2023-12-31T17:00:00+01:00

A while back I've written about the Java Native Interface (JNI) and how to use and abuse it for running native code inside your Java program, either to run legacy code or to have performance critical code run natively. However if your native code crashes, which is not that hard in C/C++, then it takes your Java program with it. If your Java program is a server applet running inside a Tomcat process for example, your whole webserver comes crashing down and a world of pain is waiting for you.

A friend of mine had quite a clever "solution" to this problem, at least on Linux. While, we would like to eliminate all sources of crashes forever, this is not possible and unrealistic, we can however make debugging a bit easier. We would like to:

catch a crash,
write a crashdump (or at least backtrace) for easier debugging,
throw an exception into the Java-world so it can try and shut down gracefully.

But first we will have to learn a few basics about Linux and Unix. And if you've missed the first JNI-article and are missing a few of the essentials, feel free to read that first.

Fundamentals about UNIX signals

Unix signals are a way in the Operating System to transfer data into a process. This is used to stop or pause a process (SIGSTOP), to notify a debugger about changes in the child process (SIGCHILD) or even to kill a process (SIGTERM, SIGKILL). Also the operating system stops a process and sends it a Signal when the process tried to execute an illegal instruction (SIGILL), tried to access invalid memory locations (SIGSEGV) or a bus error occured (SIGBUS). There is even a signal when the terminal changes in size (SIGWINCH).

Whenever a process receives such a signal, there is an action associated with it. A process may mask (i.e. disable) a signal, so it will be ignored, when it receives the signal, take the default action (which is to ingore the signal for most of them), or handle the signal itself. Afterall, most signals can just be caught, handled and the program wouldn't necessarily need to abort execution, in some cases aborting is the only reasonable way forward; with SIGTERM it is the only way to go (it cannot be caught).

Let's assume a C program like this. We have a main routine, where we set a pointer into some memory, and write to it in a loop.

#include <stdint.h>

int main () {
    uint8_t* ptr = (void*)0x400000000000;
    for ( int i = 0; i<8192; i++ ) {
        *ptr = 3;
        ptr++;
    }
}

Trying it out, we will receive a SIGSEGV (Segmentation Fault), the exact output could depend on your shell:

$ gcc main.c
$ ./a.out
fish: Job 1, './a.out' terminated by signal SIGSEGV (Segmentation Fault)

Nothing unexpected here. Clearly the 0x4... pointer points into virtual memory, that was not mapped to the process. Writing to it will cause the processor to trap into a page fault handler, where the operating system checks the address. It will look in its internal data structure and map memory to the place, if it sees that there should be something mapped (see lazy paging or the growing stack). If there is nothing mapped, a SIGSEGV signal is sent to the offending process. The default behaviour of SIGSEGV is to abort program execution.

But we can overwrite the default action and define our own with [sigaction]. If we set a signal handler for the SIGSEGV signal and map new memory into the space we just wanted to access, similar to [advent(2)], then we will be able to run our program to completion. This is just an example of what we can do. Trying this in production will break things, and you should never ever just ignore a SIGSEGV. While we are purposely writing into some random memory, most programs will trash the stack, heap or other necessary data, way before jumping into random memory.

// Have a look here: https://osg.tuhh.de/Advent/06-sigaction/
#include <stdint.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>

#include <signal.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/mman.h>

#define PAGE_SIZE 4096

void sa_sigsegv(int signum, siginfo_t* info, void* context) {
    // Calculate the page address from the fault address
    // 0xdeadbeef -> 0xdeadb000
    uintptr_t addr = (uintptr_t)info->si_addr;
    addr = addr & (~ (PAGE_SIZE - 1));

    // MMAP one page of anonymous private memory to that location.
    // Afterwards, the program can continue its way to perdition.
    void *ret = mmap((void*)addr, PAGE_SIZE,
                     PROT_READ|PROT_WRITE,
                     MAP_PRIVATE|MAP_ANONYMOUS,
                     -1, 0);
    if (ret == MAP_FAILED) {
        perror("mmap");
        exit(-1);
    }
}

int main () {
    struct sigaction sa;
    memset(&sa, 0, sizeof(sa));
    sa.sa_flags     = SA_SIGINFO | SA_RESTART;
    sa.sa_sigaction = &sa_sigsegv;
    sigemptyset(&sa.sa_mask);
    if (sigaction(SIGSEGV, &sa, NULL) != 0) {
        perror("sigaction");
        return -1;
    }

    uint8_t* ptr = (void*)0x400000000000;
    for ( int i = 0; i<8096; i++ ) {
        *ptr = 3;
        ptr++;
    }
}

A Caveat

Some of you reading this, will scream at the piece of code above. A signal handler can be called by the OS at any time, so we have no information about locks that are held or the state of other threads. They could be in the kernel right now, trying to allocate memory or may be altering important global data structures.

Make no mistake, we are trying to do something useful in a Unix signal handler, which it is not there for. There are several sources warning developers about doing anything more than setting a global flag (and even that might be racey). Accessing global data is tabu, executing asynchronous calls, that could use locks internally is tabu. Let's just say, everything fun should not be avoided in signal handlers.

What we are about to do works for my friend, but it most definitely might not work for you. It is based on undefined behaviour, which might lead to nothing bad hapenning at all, random signals or crashes, subtle behavioural changes or nasal daemons.

What we want to achieve

The above example shows a use case for a signal handler (ignoring the quite obvious warnings about signal handlers). Most of the times, SIGSEGV should not be overwritten, or if so only to print some more information (which is still undefined behaviour). Some signals, like SIGSEGV indicate a program error, that cannot be recovered from. When you receive SIGSEGV you cannot be certain, that all the process' memory is intact.

However. We want to run a Java-program, that links to native code via the Java Native Interface (JNI). The scenario is, that we have a library of legacy code, that cannot easily be ditched or rewritten in Java, so for the time being we will need to run this unsafe code and shield it, as good as we can, from potentially malicious user input.

Unsafe native code can however still crash. In C or C++ it is easy to forget the lifetime of your objects, forget to check a pointer for null or to ensure, that the object you want to call is the object you are trying to call. Java protects you from some of these errors with its type safety approach and garbage collection.

But, anyway. Your native code could crash, it could bring down your whole Java process with it. Remember, if we catch a SIGSEGV signal and if we don't handle it (assuming the Java JVM doesn't gracefully ignore it), the whole process is aborted, include everything that runs inside it, if that is a whole Tomcat webserver, it will come down as well. Very ungraceful.

So, let's try and catch the crash, gather some information and maybe even let our Java program catch an Exception and shut down somewhat gracefully.

Glueing it back together

In my previous article we've set up a thin wrapper glue library, that is actually loaded by the Java VM, converts parameter types and jumps into our native C/C++ code. Who says we can't use this library to have some fun?

Firstly, we will need a signal handler. This is were this mechanism could become quite unstable: the Java Virtual Machine uses signals itself, so overwriting or chaining signal handlers the wrong way can break (future versions) of our Java program, so I wouldn't recommend this approach to use in production. You've been warned.

But still, let's write ourselves a signal handler in our glue-library, that gathers a crash log, prints it to stderr and exits:

void SignalHandler( int signum, siginfo_t* si, void* uc ) {
    std::cerr << "Signal " << signum << " (SIG" << sigabbrev_np(signum) << ")" << std::endl;

    void** buffer = malloc(64 * sizeof(void*));
    int num = backtrace ( buffer, 64 );
    backtrace_symbols_fd ( buffer, num, STDERR_FILENO );
    abort();
}

jint JNI_OnLoad( JavaVM* vm, void* res ) {
    struct sigaction sa;
    memset(&sa, 0, sizeof(sa));
    sa.sa_flags     = SA_SIGINFO | SA_RESTART;
    sa.sa_sigaction = &SignalHandler;
    sigemptyset(&sa.sa_mask);
    if (sigaction(SIGSEGV, &sa, NULL) != 0) {
        std::cout << "[FATAL] sigaction failed" << std::endl;
        return -1;
    }

    return JNI_VERSION_1_2;
}

We've created an oddly looking function, JNI_OnLoad. This function is called by Java, when the library is loaded. It is there to initialize the native library; many C libraries need to call an initializer function for preparing internal data structures before doing anything useful. We use it to register a signal handler. A similar function exists for Unloading a library, see [Java: Invocation API];

But are we actually registering a signal handler though? If we read a bit more of the JVM docs, we will find [Java: Signal Handling] and [Java: Signal Chaining]. If we just try to use this piece of code and not bother with anything else, our Java program will crash occasionally, for example when some NullPointer Exceptions would be thrown, or maybe when new objects will be allocated. That's no fun.

The JVM uses Unix Signals to detect null pointer accesses and uses those to generate a NullPointer Exception. It also uses Unix Signals to "automatically" grow Java stacks. We've just overwritten a used Signal Handler of our JVM, so we're hindering the JVM to do its job.

The JVM has a facility to catch Signals, that the JVM doesn't know what to do with: Signal Chaining. If we preload libjsig.so, it will overwrite calls like sigaction. This way and call to sigaction is intercepted, it stores our signal handler internally. If the JVM catched a signal, that it cannot do anything useful with in it own handlers, it will call (chain) our signal handler behind it's own.

This behaviour includes some SIGSEGV errors (some are caught by JVM to implement an auto growing stack). This also means, we have no control over the real signal handler, but we can execute code, if signals are caught.

To preload libjsig.so, so we'll load it before the libc, which would set sigaction itself, we need to invoke our program with the LD_PRELOAD (see [ld.so]) environment set:

LD_PRELOAD=/usr/lib/jvm/java-17-openjdk/lib/server/libjsig.so java -jar jnitest.jar

Sending a SIGSEGV to the process (or provoking one from native code), will lead to output like this:

Hello World
Signal 11 (SIGSEGV)
/home/naums/jni-test/build/libJniGlue.so(SignalHandler+0xb0)[0x7f8034f96289]
/usr/lib/libc.so.6(+0x3e710)[0x7f8035188710]
/home/naums/jni-test/build/libJniNative.so(native_hello_world+0x3f)[0x7f8034f8c158]
/home/naums/jni-test/build/libJniGlue.so(Java_de_snaums_jnitest_java_1hello_1world+0x15)[0x7f8034f96394]
[0x7f801c74453a]
fish: Job 1, 'java -jar jnitest.jar' terminated by signal SIGABRT (Abbruch)

So now we have a backtrace on stderr.

Longjumping back to Java

Nice, we get a backtrace, this should at least help to identify problems and fix them in the native code, if they arise. But our process is still gone.

Maybe you've found the functions setjmp and longjmp before, and maybe you've wondered about what they could be used for. These functions perform a "nonlocal goto", which is not that useful of a description if you're new to them.

In essence, setjmp stores the current processor state, and longjmp returns back to it. They will not alter any (global) data, they won't unwind the stack, they will quite literally just jump back, like a goto. setjmp in a sense returns two times: once setting the jump, once returning through longjmp. One could use it to implement exceptions and their non-local returns (if you don't need stack-unwinding, that is).

Let's first see, how we use setjmp normally, albeit a bit useless:

#include <iostream>
#include <setjmp.h>

int main() {
    jmp_buf buf;
    std::cout << "Starting program" << std::endl;

    // first return: rc will be 0
    // second return: will be 1 (set by longjmp)
    int rc = setjmp(buf);

    std::cout << "Starting calculation" << std::endl;
    // some random maths
    int c;
    int d = c + 12;
    c = 30;

    std::cout << "Value of d:" << d << std::endl;

    if ( rc == 0 ) {
        longjmp ( buf, 1 );
    }

    return 0;
}

$ g++ setjmp.cpp
$ ./a.out
Starting program
Starting calculation
Value of d:32674
Starting calculation
Value of d:42

Ah, hang on. What happened here? We've forgot to initialize c, so it is unitialized when we first start. The value of d is calculated from c. Then we set c to 30. On our second pass through (returning a second time from setjmp), we use the correct value of c. So setjmp and longjmp cannot be used to turn back time, but rather to jump to more or less arbitrary places in your program more or less safely (a lot safer, than if you were to implement a non-local jump yourself in assembly).

Now, we can use it to return control back to our Java program and maybe raise an Exception, so the Java-side could in theory shutdown cleanly. So we extend our glue-library:

static jmp_buf longjmp_buffer;

void SignalHandler( int signum, siginfo_t* si, void* uc ) {
    std::cerr << "Signal " << signum << " (SIG" << sigabbrev_np(signum) << ")" << std::endl;

    void** buffer = (void**) malloc(64 * sizeof(void*));
    int num = backtrace ( buffer, 64 );
    backtrace_symbols_fd ( buffer, num, STDERR_FILENO );
    // here we jump back to the glue-function
    longjmp( longjmp_buffer, 1 );
}

// JNI_OnLoad ...

// we create and throw a NoClassDefFoundError exception
jint throwException(JNIEnv* env) {
    jclass exClass;
    char *className = "java/lang/NoClassDefFoundError";

    exClass = env->FindClass(className);
    if (exClass == NULL) {
        std::cerr << "Could not find NoClassDefFoundError, Aborting" << std::endl;
        abort();
    }

    return env->ThrowNew(exClass, "A JNI Problen occurred");
}

void Java_de_snaums_jnitest_java_1hello_1world 
    (JNIEnv * env, jclass cls) {
        // setting the longjmp. The second time (error case), we'll
        // raise an exception
        if ( setjmp ( longjmp_buffer ) == 0 ) {
            native_hello_world();
        } else {
            throwException( env );
        }
}

jint Java_de_snaums_jnitest_java_1sum
    (JNIEnv *env, jclass cls, jint first, jint second) {
        // setting the longjmp. The second time (error case), we'll
        // raise an exception
        if ( setjmp ( longjmp_buffer ) == 0 ) {
            return (jint) native_sum( (int)first, (int)second );
        } else {
            throwException( env );
        }
}

So, the output is, if I introduce a write access to nullpointer in native_hello_world:

$ java -jar jnitest.jar
Hello World
Signal 11 (SIGSEGV)
/home/naums/jni-test/build/libJniGlue.so(SignalHandler+0xb0)[0x7fd09b1942d9]
/usr/lib/libc.so.6(+0x3e710)[0x7fd09b35a710]
/home/naums/jni-test/build/libJniNative.so(native_hello_world+0x3f)[0x7fd09b18a158]
/home/naums/jni-test/build/libJniGlue.so(Java_de_snaums_jnitest_java_1hello_1world+0x2d)[0x7fd09b19448c]
[0x7fd08474453a]
Exception in thread "main" java.lang.NoClassDefFoundError: A JNI Problen occurred
    at de.snaums.jnitest.java_hello_world(Native Method)
    at de.snaums.fun.main(fun.java:10)

We've thrown NoClassDefFoundError as a placeholder, you might want to lookup a list of predefined Exceptions or create a new Exception class yourself to throw. The only thing missing is to catch this Exception, I leave it as a task for the reader.

Oh Stack, my Stack

So we've solved the SIGSEGV problem, right? Right?

Yeah, no. We receive a SIGSEGV when we try to write a memory location that does not belong to us, that includes random stray write to anywhere. But, a SIGSEGV would also be raised when your native stack is running out of room. Linux allocates an 8MB stack area (see ulimit) for your processes. Your native stack will grow to that size automatically, but can't extend over that limit.

So, when we introduce an infinite recursion (in native_hello_world) and fill our native stack, we should see a SIGSEGV and handle it in our handler.

$ LD_PRELOAD=/usr/lib/jvm/java-17-openjdk/lib/server/libjsig.so  java -jar jnitest.jar
...
Hello World
Hello World
Hello World
Hello World
fish: Job 1, 'java -jar jnitest.jar' terminated by signal SIGSEGV (Segmentation fault)

Aha! We get a SIGSEGV, but our native signal handler is not called. Well we've exhausted our stack area, so the libc has no room to place the return address and signal information on the stack and call our signal handler. This causes the process to receive a second SIGSEGV while trying to prepare handling the first one. Now the kernel will hard-abort our application.

Luckily in UNIX there is a function [sigaltstack], with which we can register an alternative stack for signal handlers to use. Then, when a signal is caught the operating system will switch the signal handler to this alternate stack, place the return information on there, and starting our signal handler.

Let's try that in a normal C++-Test program:

#include <signal.h>
#include <sys/mman.h>
#include <cstring>
#include <cstdlib>

#include <iostream>

// we could also use SIGSTKSZ
#define SIGNAL_STACK_SIZE 4096*4

void setup_alternate_stack () {
    int8_t *mem = ( int8_t * )mmap( NULL,
                                    SIGNAL_STACK_SIZE + 2 * getpagesize(),
                                    PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANON,
                                    -1, 0 );
    if ( mem == MAP_FAILED )
    {
        std::cout<< "[FATAL] Unable to mmap Signal stack " << std::endl;
    }
    else
    {
        // We set up 2 Guard pages, one before our stack, one after
        // so if we write over the end while executing the signal handler
        // we will be killed (safely)
        mprotect( mem, getpagesize(), PROT_NONE );
        mprotect( mem + getpagesize() + SIGNAL_STACK_SIZE, getpagesize(), PROT_NONE );

        stack_t ss;
        memset( &ss, 0, sizeof( stack_t ) );
        ss.ss_flags = 0;
        ss.ss_size = SIGNAL_STACK_SIZE;
        ss.ss_sp = mem + getpagesize();;

        stack_t os;
        memset( &os, 0, sizeof( stack_t ) );
        int rc = 0;
        rc = sigaltstack( &ss, &os );
        if ( rc != 0 )
        {
            std::cout << "[FATAL] Setting alternate signal stack failed " << std::endl;
        }
        else
        {
            std::cout << "[INFO ] Set alternate signal stack " << std::endl;
        }
        std::cout << "Original stack: " << os.ss_sp << " size " << os.ss_size << " flags " << os.ss_flags << std::endl;
    }
}

void recurse(int b) {
    int a = 12;
    recurse(a);
}

void SignalHandler(int signum, siginfo_t* si, void* ucontext) {
    std::cout << "Hello from Stack " << &signum << std::endl;
    abort();
}

int main() {
    setup_alternate_stack();

    struct sigaction sa;
    memset(&sa, 0, sizeof(sa));
    // SA_ONSTACK is needed for the handler to run on the alternate stack
    sa.sa_flags     = SA_SIGINFO | SA_RESTART | SA_ONSTACK;
    sa.sa_sigaction = &SignalHandler;
    sigemptyset(&sa.sa_mask);
    if (sigaction(SIGSEGV, &sa, NULL) != 0) {
        std::cout << "[FATAL] sigaction failed" << std::endl;
        return -1;
    }

    recurse(12);
}

Yes, this works.

[INFO ] Set alternate signal stack
Original stack: 0 size 0 flags 2
Hello from Stack 0x7f6f59a7e9ac
fish: Job 1, './a.out' terminated by signal SIGABRT (Abbruch)

Now let's try it with Java, adding the alt-stack:

LD_PRELOAD=/usr/lib/jvm/java-17-openjdk/lib/server/libjsig.so java -jar jnitest.jar
...
Hello World
Hello World
fish: Job 1, 'LD_PRELOAD=/usr/lib/jvm/java-17…' terminated by signal SIGSEGV (Adressbereichsfehler)

Hm, funny. It doesn't work.

Let's remind ourselves, Java handles (some) signals itself, like SIGSEGV. Java needs to handle some signals itself, so it registers its own signal handlers with the system. Preloading libjsig.so will prevent the native code from registering its native handlers with the system, rather the JVM stores them and will chain them after its own handlers.

This also means, that the Java signal handlers would run on the alternate stack, if this were successful. Unfortunately it isn't. Look at our pure C++ example from above. We've added a flag to our sigaction call: SA_ONSTACK. This is necessary, so the Signal Handler will be using our alternate stack. If it is missing, the alternate stack is not used for this signal handler. And this missing flag is our problem here.

Unfortunately there is no way for us to overwrite the JVMs signal registrations.

Going Bonkers

Or is there?

Remember, libjsig intercepts sigaction, but it cannot intercept the pure systemcall if we manage to call it ourselves. Funnily enough, the libc presents us a "nice" wrapper for it, the syscall function. Let's use it to call sigaction on the Java SIGSEGV handler and hard-set the SA_ONSTACK flag.

#include <sys/syscall.h>
#include <unistd.h>

// this is stupid, do never do this in real life
struct sigaction java_handler;
syscall( SYS_rt_sigaction, SIGSEGV, nullptr, &java_handler, sizeof( sigset_t ) );
if ( java_handler.sa_handler != SIG_DFL ) {
    std::cout << "attempting something very stupid" << std::endl;
    java_handler.sa_flags |= SA_ONSTACK;
    syscall( SYS_rt_sigaction, SIGSEGV, &java_handler, nullptr, sizeof( sigset_t ) );
}

We call it twice here, first to get the old handler back, so the one that the JVM set, we'll add the SA_ONSTACK flag, and set the structure again.

Even if we place this code right before the recursion call, we will have no luck, unfortunately.

...
Hello World
attempting something very stupid
fish: Job 1, 'LD_PRELOAD=/usr/lib/jvm/java-17…' terminated by signal SIGSEGV (Adressbereichsfehler)

Somewhere in the JVM it probably resets the handlers or maybe the JVM expects to be on it's normal C stack? I was unable to find out the reason, and more altering of the JVM from the outside would not increase or guarantee coverage. So let's stop here.

Conclusion

In this article we've seen that we (sometimes) are able to use signal handlers and signal chaining in native code linked to a Java VM via Java Native Interface (JNI) to handle some errors, report backtraces and maybe even raise exceptions and return to Java. The Java world should then be as short as possible, never allocate more memory, just shut down and maybe restart.

Keep in mind, that most of what we've done in our signal handlers is illegal and may introduce security bugs, leak data or both. So while this is a nice technical excersice, it should never be used in production code. Also there are some native bugs, that cannot be reported by this method, so using a solid mechanism to get coredumps externally should be used, to at least find the bugs that crash the legacy code and eliminate them.

Image Reference

Heartbeat Pattern by juice_fish on freepik.com

References

JNI Basics: Calling Native Code from Java

2023-11-19T23:00:00+01:00

Have you ever wondered, how you could call native C/C++ Code from your Java Code? Say you have a library, that does exactly what you want either because it is legacy code that you want to wrap within Java or you have found an obscure problem, where no Java solution exists. Of course you could rewrite it in Java, which is insanely costly, time consuming and you will get it wrong the first few times. Altenatively you might use the Java Native Interface (JNI) for calling the native code, let's say C++ code, directly.

This article tries to explain how to use JNI in a cook book fashion. We will be using CMake to build our C++ code. We will be working on a Linux System, so the paths and linking behaviour of other systems may be different.

Before we start

We are going to link a Java program to native C/C++ code. This is quite a handy way of using old code or maybe run performance critical code natively and have the user interface run in the type safe Java language.

However, this approach also has its shortcomings. If you already know interfaces like COM in Windows then you understand, that COM runs your library in a separate server process. If your COM library crashes it only takes down the server process; your Java (or C# or whatever) client process remains intact, sees an error and can handle it in the safe world appropriately (e.g. by restarting the server and showing an error message). This of course comes with a (heavier) price in performance.

Now, JNI uses the loader/dynamic linker to load your native libraries into the Java process. While the native function is now present in the same process, there might still be a dozen or so steps between Java and the first of our native functions, so it will incur some run-time overhead over going completely native. Even worse if your native code crashes, which is easier done than said in C/C++, it will take your whole Java process with it and whatever lives in there. If you run a Tomcat in the same process it will go as well.

Even more nasty, the native code could ruin your whole memory and you might not even catch it. While Java guards the memory quite well from the Java programmers, native code can do nearly whatever it wants. It can read the whole Java heap, the JVM binary code, etc, and it could also write to it, without the operating system intervening, well at least if Write XOR Execute is not activated.

So keep in mind: you must guard native code from user input. Handling malformed or even malicious input in C++ is no easy task. If you don't get it right you might leak memory or crash the whole process. Use the strength of the Java type system to your advantage.

Prerequisites

We will be using the following tools, so make sure to install them in your distribution: * javac * cmake * gcc

Also make sure, the following libraries are installed on your system. On Arch Linux these are installed into /usr/lib/jvm/java-17-openjdk/lib/server. I'm going to use jdk17-openjdk. * libjni.so * libjvm.so

On Arch Linux it should suffice to install these packages:

$ pacman -Syu jdk17-openjdk jdk17-openjre cmake gcc g++

Starting with the Native Code

We'll be starting with our native code. In our example, we'll have two functions, one that just prints Hello World, takes no arguments and has no return values. And a second one, that sums two integer-parameters and returns the resulting integer. I'll prefix both with native_, which has no significance other than making clear, that this is our native code. So this is our legacy.cpp:

// legacy.cpp
#include <iostream>

extern "C" {
    void native_hello_world() {
        std::cout << "Hello World" << std::endl;
    }

    int native_sum( int a, int b ) {
        return a+b;
    }
}

For easier reading, I've marked these functions as extern-C. This will deactivate C++ name mangling for these functions. In our example it wouldn't make a difference, because we'll create a separate glue-layer between Java and our native code anyways.

Building this code to a library in CMake looks like this. Place this code in the CMakeLists.txt next to your code.

# CMakeLists.txt
cmake_minimum_required (VERSION 3.5)
project (JniTest)

add_library(JniNative SHARED legacy.cpp)

Then configure the project and build it like this:

$ mkdir build
$ cd build
$ cmake ..
$ make

Now we have build our native "legacy" code, that could have been used in some project from C++. Running nm on the resulting libJniNative.so reveals these two exported symbols (the capital T indicates a .text-symbol (code), that is exported):

$ nm libJniNative.so
0000000000001109 T native_hello_world
0000000000001129 T native_sum

We'll also prepare a header file legacy.h to export these function names to other C++ compilation units, so we can use it later:

// legacy.h
extern "C" {
    void native_hello_world();
    int native_sum( int a, int b);
}

Preparing the Java-Code

Now we'll have to tell Java the names and signatures of our functions and that these functions will be native code. We'll start with the Hello-World function. In a file called jnitest.java, we'll create a public class jnitest, with a native static function java_hello_world and one java_sum with two parameters and an int return value. Note int and Integer are two different types in Java, we want to use the int-type here, so we won't need to convert it to C++ ints later on.

But it has a twist. We create a static block in the class, where we tell the Java Virtual Machine to load a library into. We will reference a glue-library, which we'll have to create. This load will fill out the code of both native functions, so calling them later from the Java side will actually land us in our native code.

// jnitest.java
package de.snaums;

public class jnitest {
    static {
        System.loadLibrary("JniGlue");
    }

    public static native void java_hello_world();
    public static native int java_sum( int a, int b );

    public static void main( String[] args ) {
            jnitest.java_hello_world();
            System.out.println("Sum: 1+2: " + jnitest.java_sum(1,2));
    }
}

This code will not run because Java will not understand the link between java_* functions and our native_* functions. We will have to create glue code for this mapping.

Creating a glue library is a bit more work, but the scenario is, that the legacy code comes directly from some other project and we wouldn't want to alter it for this. So we'll have to introduce a small wrapper around the native code. Afterall we'll have to convert our parameters for the sum-function from Java into C/C++ types.

Compile this code with the Java Compiler manually to a class-file, to see that this works. Running it won't do, because we have yet to create the glue.

javac jnitest.java

Sniffing some Glue-Code

For Java, our functions are actually called de.snaums.jnitest.java_hello_world. We've created a package de.snaums, in it a class jnitest and this class has the Java-end of our native functions in them. However the implementation of these functions is still missing, we'll have to call our native legacy code. Implementing these calls will be done in C++ again in our glue-library.

Using the Java Compiler we generate a header file for the native glue functions, with the -h parameter, followed by the output directory and the source file to be analyzed.

javac -h . jnitest.java

This will create a de_snaums_jnitest.h, with both of our functions declared, but we will need to write the wrapper code ourselves.

// de_snaums_jnitest.h/glue.h
/* DO NOT EDIT THIS FILE - it is machine generated */
#include <jni.h>
/* Header for class de_snaums_jnitest */

#ifndef _Included_de_snaums_jnitest
#define _Included_de_snaums_jnitest
#ifdef __cplusplus
extern "C" {
#endif
/*
 * Class:     de_snaums_jnitest
 * Method:    java_hello_world
 * Signature: ()V
 */
JNIEXPORT void JNICALL Java_de_snaums_jnitest_java_1hello_1world
  (JNIEnv *, jclass);

/*
 * Class:     de_snaums_jnitest
 * Method:    java_sum
 * Signature: (II)I
 */
JNIEXPORT jint JNICALL Java_de_snaums_jnitest_java_1sum
  (JNIEnv *, jclass, jint, jint);

#ifdef __cplusplus
}
#endif
#endif

Note that the function names are export'ed "C" in C++, so the C++ name mangling is deactivated. If it were to interfere with function names, the Java runtime would be unable to link the native java calls to the symbol names in our library, because it has no concept of the C++ name mangling algorithm in each compiler.

Now we need to implement these two functions in a glue.cpp. We'll start with our Hello-World function, it takes no parameters and no return values, so we can just call the function straight up. The sum-function will need a bit more work, because we would need to convert the types. However Java-int types are essentially C++ ints, if we aren't going too crazy.

// glue.cpp
#include "legacy.h"
#include <jni.h>

extern "C" {
    void Java_de_snaums_jnitest_java_1hello_1world 
        (JNIEnv *, jclass) {
            native_hello_world();
    }

    jint Java_de_snaums_jnitest_java_1sum
        (JNIEnv *env, jclass cls, jint first, jint second) {
            return (jint) native_sum( (int)first, (int)second );
    }
}

We'll compile this code into a library (libJniGlue), in a sense same as before. However, we will need to link it to some Java libraries, which have loads of functionality to convert to and from native/Java data structures. In this example we've essentially just casted the integer types. When using classes in Java as parameters for native functions, have fun converting them into C/C++ native types.

Now we have all the pieces together and could start running our Java program, have it load our glue-library, which in turn loads the "legacy" native code and we have execution.

CMake Compilation

To make it a bit more elegant, let's use CMake to build everything. We've already had a CMakeLists.txt for building our native code, now include making the Java code into a Java Archive (jar) and also building our glue library:

// CMakeLists.txt
cmake_minimum_required (VERSION 3.5)
project (JniTest)

find_package (Java REQUIRED)
find_package (JNI REQUIRED)
include (UseJava)

# Example without JNI. Simple HelloWorld class with an entry point.
add_jar (jnitest
         VERSION 0.0.1
         ENTRY_POINT de.snaums.jnitest
         SOURCES jnitest.java)

add_library(JniNative SHARED legacy.cpp)
add_library(JniGlue SHARED glue.cpp)
target_include_directories(JniGlue PRIVATE ${JNI_INCLUDE_DIRS})
target_link_libraries(JniGlue PRIVATE ${JNI_LIBRARIES} JniNative)

We include the Java-Packages for CMake for the interesting Java-parts: having the Java library and include directories preset. After including Java, we instruct CMake to build a jar jnitest.jar from jnitest.java, with a given entry point.

Then we add both the native library and the glue library and state the dependencies for the glue library, both the include directory of jni.h and the Java libraries. Importantly, we also have to link our glue library to our "legacy" code, we want to call into our "legacy" code afterall.

Running the jar

Now just run the jar, right?

$ java -jar jnitest.jar
Exception in thread "main" java.lang.UnsatisfiedLinkError: no JniGlue in
java.library.path: /usr/java/packages/lib:/usr/lib64:/lib64:/lib:/usr/lib
    at java.base/java.lang.ClassLoader.loadLibrary(ClassLoader.java:2458)
    at java.base/java.lang.Runtime.loadLibrary0(Runtime.java:916)
    at java.base/java.lang.System.loadLibrary(System.java:2059)
    at de.snaums.jnitest.<clinit>(jnitest.java:5)

Ah, now that's not good. Java loads the jar-file correctly, but then hits a bit of a snag, because it can't find our glue library. Let's look at the directories contents:

$ ls
cmake_install.cmake    jnitest-0.0.1.jar    libJniNative.so
CMakeCache.txt         jnitest.jar          Makefile
CMakeFiles             libJniGlue.so

Ok, so the libraries are clearly there. Well, Linux will only look for libraries in the system paths, and we can see it clearly in the output of Java, because it helpfully lists all the places it looked for our code. We can extend this list, by setting the environment variable LD_LIBRARY_PATH.

This environment variable does not only serve Java as a guide where to find libraries, the Linux loader will look in the given places first. It is quite a handy tool, when you explicitly don't want the libraries of the system, e.g. because you linked your program against a different version of a shared object.

Anyway, let's set the environment variable:

# fish
$ set -xg LD_LIBRARY_PATH (pwd)
# bash
$ export LD_LIBRARY_PATH $(pwd)

Then run the jar again to see the output:

$ java -jar jnitest.jar
Sum: 1+2: 3
Hello World⏎

Some fun to be had

Now, what if we'd want to choose at run-time which library was loaded. Say we have several versions of our legacy code, all in the same directory (because we cannot set LD_LIBRARY_PATH in any meaningful way from within Java).

Stunningly this is possible. The static System.loadLibrary-block is not executed when the Java program is started, but when the jnitest.class is first loaded, i.e. some class or function from it is used. After that, we cannot change what was loaded. But until then, wen can have some fun.

So, if we create a new class jnitestConfig, in an own .java file, which only has one member, a String, that sometimes holds the value "JniGlue". You see where this is going? From a third .java file - the new entry point - we can then alter the static config class member as long as we haven't called into jnitest.

So, lets add jnitestConfig.java first:

// jnitestConfig.java
package de.snaums;

public class jnitestConfig {
    public static String library = "JniGlue";
}

Then add a third .java file, which might present our user-interface. In this case I'll just try and load whatever is in the first parameter of our Java-Program:

// fun.java
package de.snaums;

public class fun {
    public static void main( String[] args ) {
        if ( args.length > 0 ) {
            jnitestConfig.library = args[0];
        }

        jnitest.java_hello_world();
    }
}

The System.loadLibrary now looks like this:

// in jnitest.java
    // ..
    static {
        System.loadLibrary( jnitestConfig.library );
    }
    // ...

Now running the program does exactly what we had before, but we could change the library to be loaded at run-time. If that ever might be useful to you, here you go.

$ java -jar jnitest.jar
Hello World
$ java -jar jnitest.jar unhold
Exception in thread "main" java.lang.UnsatisfiedLinkError: no unhold in java.library.path:
/home/snaums/jni-test/build:/usr/java/packages/lib:/usr/lib64:/lib64:/lib:/usr/lib
    at java.base/java.lang.ClassLoader.loadLibrary(ClassLoader.java:2458)
    at java.base/java.lang.Runtime.loadLibrary0(Runtime.java:916)
    at java.base/java.lang.System.loadLibrary(System.java:2059)
    at de.snaums.jnitest.<clinit>(jnitest.java:5)
    at de.snaums.fun.main(fun.java:10)

Please be aware, this is probably not in the spec of the JVM or JNI, so it might break. You probably shouldn't use this in production code.

Conclusion (tl;dr)

What have we done? We've created a Java class jnitest with 3 methods: one main-function as an entry point to the jar. Two of the methods are marked as native calls.

We've then created a header file with javac -h from the Java file and implemented these functions. The implementation is in a separate glue-library; you could also link it directly to your native code, if you know what you are doing and these calls somehow already fulfilled the interfaces.

From this point on, we can use the native functions of our legacy code from anywhere in our Java program. This can be helpful if you can't replace the native code with Java code easily.

While this article only touches on some very basic features, there are great articles and tutorials out there on some more advanced stuff, like allocating Java objects from native code, setting attributes or even throwing Exceptions. A good starting point might be Baeldungs Guide to JNI.