Fork me on GitHub

Compatibility Considerations

Versioning and Update Policy

junixsocket versions consist of three parts: major, minor and patch (for example, 2.5.1).

“Minor version” updates (e.g., 2.4.0 -> 2.5.0) can still bring “major” new features but they should be backwards compatible to releases of the same “major version” (e.g., 2.x).

The existing API should always be backwards compatible between minor releases (e.g., 2.4.0 -> 2.5.1) unless explicitly mentioned in the changelog below (e.g., dropping Java 7 support in 2.5.0).

Bugs that are found in an older version (e.g., 2.6.1) may be fixed in a minor release (e.g., 2.7.0) or a patch release (e.g., 2.6.2). There is no guarantee of a new patch release if there is a minor release coming up (as a particular example, there won't be a 2.6.3 for bugs found in 2.6.2 and earlier).

-SNAPSHOT builds are not considered releases, but merely previews of a future release.

If you have certain business reasons to not upgrade but still need something fixed, please ask for an enterprise support plan.

Supported Java versions

junixsocket 2.10.1 is fully compatible with Java 8 and newer (tested up to Java 24).

Supported Java VMs

junixsocket has been tested to work with Oracle's Java 8 JDK, and OpenJDK (and its flavors, as well as IBM Semeru) for newer versions, and other platform-specific VMs listed below.

junixsocket also works with GraalVM (tested with graalvm-ce-java17-22.2.0) both in OpenJDK mode and (since version 2.6.0, partially) in Native Image mode with Substrate VM. More details here.

Since version 2.7.0, junixsocket runs on Android, too.

Java 24 warnings

Java 24 introduced a warning when a library calls System.loadLibrary to load some native JNI code, something like:

WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::loadLibrary has been called by org.newsclub.net.unix.NativeLibraryLoader$StandardLibraryCandidate in an unnamed module
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled

For now, you can ignore this warning, but can also explicitly allow native access by adding a corresponding --enable-native-access= statement when invoking your JVM that uses junixsocket.

If junixsocket is referenced by a modularized project, you could add --enable-native-access=org.newsclub.net.unix. Otherwise (and this includes the selftest jar), simplify specify --enable-native-access=ALL-UNNAMED

Supported Platforms

The minimum set of supported (out of the box) platforms and processor architectures currently is:

  • macOS Intel 64-bit
  • macOS ARM 64-bit / Apple Silicon
  • Linux x86_64
  • Linux ARM 32-bit (armhf)
  • Linux ARM 64-bit (aarch64)
  • Linux s390x (“Linux on IBM Z”, “Linux on zSystems”)
  • Linux RISC-V 64-bit (rv64ifd / lp64d)
  • Linux ppc64le (POWER 64-bit Little Endian)
  • Linux loongarch64 (Loongson 64-bit)
  • Solaris x86 64-bit / OpenIndiana
  • Windows 10 Intel 64-bit and ARM 64-bit
  • Windows Server 2019
  • Windows Server 2022
  • FreeBSD (amd64)
  • OpenBSD (amd64)
  • NetBSD (amd64)
  • DragonFlyBSD (amd64)
  • IBM AIX 7 (POWER 64-bit)
  • IBM i 7 (POWER 64-bit) via PASE
  • Android (SDK version 26 or newer), aarch64/x86_64/i686/arm

Additional platforms known to work (after the JNI library has been compiled manually):

  • Solaris SPARC64
  • IBM z/OS OS/390 64-bit
  • Haiku, recommended R1/beta5 or newer. AF_UNIX datagram support is available since Haiku hrev57155, but you should use hrev57200 or newer:
    • Thanks to junixsocket selftests, a bug related to socket addresses/connection state was found and fixed in hrev57189.
    • A use-after-free bug in the kernel related to datagrams was found and fixed in hrev57194.
    • An unexpected blocking situation was found and fixed in hrev57200.

Additional platforms that should work (after the JNI library has been compiled manually):

  • Any other processor architecture with Linux, FreeBSD, OpenBSD, NetBSD, DragonFlyBSD

Additional platforms known to compile (but untested):

  • IBM z/TPF OS/390 with s390x-ibm-tpf-gcc version tpf-17r1-6
  • Minix

Remarks

Linux builds should be compatible with all major distributions, including the ones using musl (e.g., Alpine Linux).

The native-common binaries for the above platforms are built on recent release versions of either platform.

AIX support verified with IBM AIX 7.1 (7100-05-09), IBM AIX 7.2 (7200-05-03) and IBM AIX 7.3 (7300-00-01) on s922 and e980, using IBM J9 VMs (Java 8 and Java 11).

IBM i support verified with 7.1 (IBM i 7R1 / 71-11-2984-4), 7.2 (IBM i 7R2 / 72-09-2984-5), 7.3 (IBM i 7R3 / 73-07-001), 7.4 (IBM i 7R4 / 74-05-2984-1) on s922 and e980, using IBM J9 64-bit VMs (Java 8, and Java 11 where available).

IBM z/OS is supported, but you have to compile junixsocket-native from source with XLC. Alternatively, a binary build may be [requested here])(mailto:christian@kohlschutter.com?subject=junixsocket+z%2FOS+binary). Verified with z/OS V2.4 and Java 8 SR8.

IBM z/TPF is potentially supported (it compiles with s390x-ibm-tpf-gcc version tpf-17r1-6), but it hasn't been tested yet. If you would like to help test it, you may [request it here])(mailto:christian@kohlschutter.com?subject=junixsocket+z%2FTPF+binary).

Intel x86 32-bit and ARM 32-bit are supported, but binaries are not included by default. Please file an issue if you think that's a bad idea.

Support for custom architectures can be added by compiling a custom native binary on the target machine, or by cross-compiling using clang/LLVM on a suitable host.

Marginally supported platforms

The following platforms can successfully load the JNI library, but since they do not provide support for AF_UNIX, the functionality is currently too limited to call these platforms “supported”:

  • Windows 8.1 64-bit
  • Windows 10 before build 17061
  • OSv Unikernel (tested with v0.56 on qemu and firecracker); socketpair works.

This classification may change with the addition of new features beyond Unix domain sockets. Please reach out if you have some feature in mind that may be supported on these platforms.

Additional Platforms and Architectures

Upon request, support for additional systems, platforms and architectures may be added, such as OpenVMS, FUJITSU BS2000/OSD, Unisys ClearPath OS 2200, QNX, VxWorks, HP-UX, Guardian / NonStop OSS, WebAssembly WASI, etc.

If you are interested in using junixsocket on another platform, or willing to sponsor development (by providing access to such platforms, covering licensing costs, etc.), feel free to file a ticket or contact Christian Kohlschütter via email.

Selftest

A reliable way to ensure that junixsocket works in your environment is to run the “selftest”.

java -jar junixsocket-selftest-2.10.1-jar-with-dependencies.jar

The last line should say “Selftest PASSED” (or “Selftest PASSED WITH ISSUES”), then you're good to go.

If not, please file a bug report with the output of the selftest.

NOTE: If your target platform supports both 32-bit and 64-bit Java VMs, make sure to use the 64-bit version first.

For Android, there is a custom selftest app, junixsocket-selftest-android, which can be built with Android Studio, for example.

Workarounds/testing for broken setups

There is a chance that something is subtly wrong with the combination of junixsocket and your system.

To completely disable junixsocket (as if you were on a system for which no native library is available), you can set the following System property:

-Dorg.newsclub.net.unix.library.disable=true

To selectively disable a junixsocket capability, you can specify a System property as follows:

-Dorg.newsclub.net.unix.library.disable.CAPABILITY_XYZ=true

For example, in order to disable the support for passing file descriptors via ancillary messages, specify:

-Dorg.newsclub.net.unix.library.disable.CAPABILITY_FILE_DESCRIPTORS=true

The set of available capabilities is enumerated in the AFSocketCapability enum.

Bugs in other systems

If you're curious about bugs in other systems we could find thanks to junixsocket, take a look here.