JNA native binding traps

JNA (Java Native Access) maps a Java/Kotlin interface onto an already-compiled C library at runtime. Nothing checks that your declarations match the header: a wrong field order, a wrong open flag or a collected callback are all silent at link time and surface much later, somewhere else. Write the binding defensively, and log enough to tell a working setup from a broken one.

Verification commands below run against the exact jar you ship, e.g. JAR=$(find ~/.gradle/caches -name 'jna-<version>.jar' | head -1).

Traps

The open-flags option is POSIX-only — the same number means something else on Windows. Library.OPTION_OPEN_FLAGS is forwarded verbatim to the platform's loader call; JNA does not translate it. Confirm on your pinned jar: javap -p -c -classpath "$JAR" com.sun.jna.NativeLibrary | grep -n 'open-flags\|Native.open' — the option key is read and its value flows into Native.open(String, int). On POSIX, 2 is "resolve everything now". On Windows the same 2 asks the loader to map the file as plain data: it appears to load, then every symbol lookup fails, and the message names the function while blaming a missing module.