Class ForeignFunctions

java.lang.Object
oshi.ffm.ForeignFunctions
Direct Known Subclasses:
CupsFunctions, IUnknownFFM, MacForeignFunctions, WindowsForeignFunctions
public abstract class ForeignFunctions extends Object
Base class providing utility methods for working with the Java Foreign Function and Memory (FFM) API.

Subclasses use these helpers to load native libraries and frameworks, create downcall handles, and read data from native memory segments.

  • Field Details

    • LINKER

      protected static final Linker LINKER
      The native linker for the current platform.

    • LIBRARY_ARENA

      protected static final Arena LIBRARY_ARENA
      A shared auto arena used for library symbol lookups.

    • SYMBOL_LOOKUP

      protected static final SymbolLookup SYMBOL_LOOKUP
      Symbol lookup for libraries already loaded into the current process.

    • CAPTURE_CALL_STATE

      protected static final Linker.Option CAPTURE_CALL_STATE
      Linker option to capture errno after a native call.

    • CAPTURED_STATE_LAYOUT

      public static final StructLayout CAPTURED_STATE_LAYOUT
      Layout of the captured call state segment, containing errno.

    • ERRNO_HANDLE

      protected static final VarHandle ERRNO_HANDLE
      Handle to read the errno field from a captured call state segment.

  • Constructor Details

    • ForeignFunctions

      protected ForeignFunctions()
      Not intended for instantiation.

  • Method Details

    • libraryLookup

      public static SymbolLookup libraryLookup(String libraryName)
      Lookup a native library by simple name, mapping it to the platform-specific filename (e.g. "c" → "libc.so" on Linux).
      Parameters:
      libraryName - the platform-independent library name
      Returns:
      the symbol lookup for the library

    • getStructFromNativePointer

      public static MemorySegment getStructFromNativePointer(MemorySegment pointer, StructLayout layout, Arena arena)
      Reinterpret a raw native pointer as a struct of the given layout, scoped to the provided arena.
      Parameters:
      pointer - the native pointer
      layout - the struct layout
      arena - the arena to scope the resulting segment to
      Returns:
      a memory segment over the struct, or null if the pointer is null or MemorySegment.NULL

    • getStringFromNativePointer

      public static String getStringFromNativePointer(MemorySegment pointer, Arena arena)
      Read a null-terminated UTF-8 string from a raw native pointer.
      Parameters:
      pointer - the native pointer
      arena - the arena to scope the reinterpreted segment to
      Returns:
      the Java string, or null if the pointer is null or MemorySegment.NULL

    • getByteArrayFromNativePointer

      public static byte[] getByteArrayFromNativePointer(MemorySegment pointer, long length, Arena arena)
      Copy length bytes from a raw native pointer into a Java byte array.
      Parameters:
      pointer - the native pointer
      length - the number of bytes to copy
      arena - the arena to scope the reinterpreted segment to
      Returns:
      the byte array, or null if the pointer is null or MemorySegment.NULL

    • lib

      public static SymbolLookup lib(String name)
      Lookup a library by name in the global arena.
      Parameters:
      name - the library name
      Returns:
      the symbol lookup for the library

    • downcall

      public static MethodHandle downcall(SymbolLookup lib, String symbol, MemoryLayout resLayout, MemoryLayout... argLayouts)
      Create a downcall handle for a symbol in a library.
      Parameters:
      lib - the symbol lookup
      symbol - the symbol name
      resLayout - the return layout
      argLayouts - the argument layouts
      Returns:
      the method handle

    • getErrno

      public static int getErrno(MemorySegment callState)
      Read the errno value from a captured call state segment.
      Parameters:
      callState - the memory segment returned by a call made with CAPTURE_CALL_STATE
      Returns:
      the errno value