Class ErrnoCapture

java.lang.Object
express.mvp.roray.utils.functions.ErrnoCapture
public final class ErrnoCapture extends Object
Helper for capturing and interpreting errno from native calls.

When a native function fails, it typically returns -1 and sets errno to indicate the specific error. This class provides utilities to capture and interpret these error codes.

Usage Example

// Create a downcall that captures errno
MethodHandle open = factory.downcall("open", descriptor,
    ErrnoCapture.captureOption());

// Make the call with errno capture
try (Arena arena = Arena.ofConfined()) {
    MemorySegment capturedState = ErrnoCapture.allocateCaptureState(arena);
    int fd = (int) open.invokeExact(capturedState, path, flags, mode);

    if (fd < 0) {
        int errno = ErrnoCapture.getErrno(capturedState);
        throw new IOException(ErrnoCapture.strerror(errno));
    }
}

Socket Connection Example

MethodHandle connect = factory.downcall("connect", connectDesc,
    ErrnoCapture.captureOption());

try (Arena arena = Arena.ofConfined()) {
    MemorySegment state = ErrnoCapture.allocateCaptureState(arena);
    int result = (int) connect.invokeExact(state, sockfd, addr, addrlen);

    if (result < 0) {
        int errno = ErrnoCapture.getErrno(state);
        switch (errno) {
            case ErrnoCapture.EINPROGRESS -> {} // Non-blocking connect started
            case ErrnoCapture.ECONNREFUSED -> throw new ConnectException("Connection refused");
            case ErrnoCapture.ETIMEDOUT -> throw new SocketTimeoutException("Connect timed out");
            default -> throw new IOException(ErrnoCapture.strerror(errno));
        }
    }
}

Important Notes

  • When using captureCallState, the MethodHandle signature changes: a MemorySegment parameter is prepended for the captured state.
  • The captured state segment must be allocated before each call.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    EACCES
    Permission denied.
    static final int
    EAGAIN
    Resource temporarily unavailable (same as EWOULDBLOCK).
    static final int
    EALREADY
    Operation already in progress.
    static final int
    EBADF
    Bad file descriptor.
    static final int
    EBUSY
    Device or resource busy.
    static final int
    ECONNREFUSED
    Connection refused.
    static final int
    ECONNRESET
    Connection reset by peer.
    static final int
    EDEADLK
    Resource deadlock avoided.
    static final int
    EEXIST
    File exists.
    static final int
    EFAULT
    Bad address.
    static final int
    EINPROGRESS
    Operation now in progress.
    static final int
    EINTR
    Interrupted system call.
    static final int
    EINVAL
    Invalid argument.
    static final int
    EIO
    I/O error.
    static final int
    EMFILE
    Too many open files.
    static final int
    ENOENT
    No such file or directory.
    static final int
    ENOMEM
    Cannot allocate memory.
    static final int
    ENOSPC
    No space left on device.
    static final int
    ENOSYS
    Function not implemented.
    static final int
    EPERM
    Operation not permitted.
    static final int
    EPIPE
    Broken pipe.
    static final int
    ESRCH
    No such process.
    static final int
    ETIMEDOUT
    Connection timed out.

  • Method Summary

    Modifier and Type
    Method
    Description
    static MemorySegment
    allocateCaptureState(Arena arena)
    Allocates a memory segment suitable for capturing call state.
    static Linker.Option
    captureOption()
    Returns the Linker.Option to capture errno.
    static long
    captureStateSize()
    Gets the size required for the capture state segment.
    static int
    getErrno(MemorySegment capturedState)
    Extracts the errno value from a captured call state.
    static String
    strerror(int errno)
    Returns a human-readable description of an errno value.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Method Details

    • captureOption

      public static Linker.Option captureOption()
      Returns the Linker.Option to capture errno.

      When this option is used, the resulting MethodHandle will have a MemorySegment prepended to its parameter list. This segment must be allocated using allocateCaptureState(Arena) before each invocation.

      Returns:
      Linker option for capturing errno

    • allocateCaptureState

      public static MemorySegment allocateCaptureState(Arena arena)
      Allocates a memory segment suitable for capturing call state.
      Parameters:
      arena - Arena to allocate from
      Returns:
      MemorySegment for capturing errno

    • captureStateSize

      public static long captureStateSize()
      Gets the size required for the capture state segment.
      Returns:
      Size in bytes

    • getErrno

      public static int getErrno(MemorySegment capturedState)
      Extracts the errno value from a captured call state.
      Parameters:
      capturedState - The segment passed to the downcall
      Returns:
      The errno value set by the native function

    • strerror

      public static String strerror(int errno)
      Returns a human-readable description of an errno value.
      Parameters:
      errno - The error number
      Returns:
      String description of the error