Package ghidra.pcode.emu.unix

# Class AbstractEmuUnixSyscallUseropLibrary<T>

java.lang.Object
ghidra.pcode.exec.AnnotatedPcodeUseropLibrary<T>
ghidra.pcode.emu.sys.AnnotatedEmuSyscallUseropLibrary<T>
ghidra.pcode.emu.unix.AbstractEmuUnixSyscallUseropLibrary<T>

Type Parameters:
  `T` - the type of values processed by the library

All Implemented Interfaces:
  `EmuSyscallLibrary<T>`, `PcodeUseropLibrary<T>`

Direct Known Subclasses:
  `AbstractEmuLinuxSyscallUseropLibrary`

public abstract class AbstractEmuUnixSyscallUseropLibrary<T> extends AnnotatedEmuSyscallUseropLibrary<T>
An abstract library of UNIX system calls, suitable for use with any processor

See the UNIX manual pages for more information about each specific system call, error numbers, etc.

TODO: The rest of the system calls common to UNIX.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `AbstractEmuUnixSyscallUseropLibrary.Errno`
  The errno values as defined by the OS simulator
  `protected class`
  `AbstractEmuUnixSyscallUseropLibrary.UnixStructuredPart`
  System calls defined using Structured Sleigh

  ## Nested classes/interfaces inherited from class ghidra.pcode.emu.sys.AnnotatedEmuSyscallUseropLibrary

  `AnnotatedEmuSyscallUseropLibrary.EmuSyscall, AnnotatedEmuSyscallUseropLibrary.StructuredPart`

  ## Nested classes/interfaces inherited from class ghidra.pcode.exec.AnnotatedPcodeUseropLibrary

  `AnnotatedPcodeUseropLibrary.AnnotatedPcodeUseropDefinition<T>, AnnotatedPcodeUseropLibrary.FixedArgsAnnotatedPcodeUseropDefinition<T>, AnnotatedPcodeUseropLibrary.OpExecutor, AnnotatedPcodeUseropLibrary.OpLibrary, AnnotatedPcodeUseropLibrary.OpOutput, AnnotatedPcodeUseropLibrary.OpState, AnnotatedPcodeUseropLibrary.PcodeUserop, AnnotatedPcodeUseropLibrary.VariadicAnnotatedPcodeUseropDefinition<T>`

  ## Nested classes/interfaces inherited from interface ghidra.pcode.emu.sys.EmuSyscallLibrary

  `EmuSyscallLibrary.EmuSyscallDefinition<T>, EmuSyscallLibrary.SyscallPcodeUseropDefinition<T>`

  ## Nested classes/interfaces inherited from interface ghidra.pcode.exec.PcodeUseropLibrary

  `PcodeUseropLibrary.EmptyPcodeUseropLibrary, PcodeUseropLibrary.PcodeUseropDefinition<T>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final NavigableSet<Integer>`
  `closedFds`
  `protected final Map<Integer,EmuUnixFileDescriptor<T>>`
  `descriptors`
  `protected final EmuUnixFileSystem<T>`
  `fs`
  `protected final int`
  `intSize`
  `protected EmuUnixUser`
  `user`

  ### Fields inherited from class ghidra.pcode.emu.sys.AnnotatedEmuSyscallUseropLibrary

  `additionalArchives, CACHE_BY_CLASS, cSpec, dtMachineWord, machine, program, SYSCALL_SPACE_NAME, syscallMap`

  ### Fields inherited from class ghidra.pcode.exec.AnnotatedPcodeUseropLibrary

  `ops`

  ### Fields inherited from interface ghidra.pcode.emu.sys.EmuSyscallLibrary

  `SYSCALL_CONVENTION_NAME`

  ### Fields inherited from interface ghidra.pcode.exec.PcodeUseropLibrary

  `NIL`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AbstractEmuUnixSyscallUseropLibrary(PcodeMachine<T> machine, EmuUnixFileSystem<T> fs, Program program)`
  Construct a new library
  `AbstractEmuUnixSyscallUseropLibrary(PcodeMachine<T> machine, EmuUnixFileSystem<T> fs, Program program, EmuUnixUser user)`
  Construct a new library

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected int`
  `claimFd(EmuUnixFileDescriptor<T> desc)`
  Claim the lowest available file descriptor number for the given descriptor object
  `protected abstract Set<EmuUnixFileSystem.OpenFlag>`
  `convertFlags(int flags)`
  Convert the flags as defined for this platform to flags understood by the simulator
  `protected EmuUnixFileDescriptor<T>`
  `createHandle(EmuUnixFile<T> file, int flags)`
  A factory method for creating an open file handle
  `protected EmuUnixFileDescriptor<T>`
  `findFd(int fd)`
  Get the file descriptor object for the given file descriptor number
  `protected abstract int`
  `getErrno(AbstractEmuUnixSyscallUseropLibrary.Errno err)`
  Get the platform-specific errno value for the given simulator-defined errno
  `boolean`
  `handleError(PcodeExecutor<T> executor, PcodeExecutionException err)`
  Try to handle an error, usually by returning it to the user program
  `protected int`
  `lowestFd()`
  Get the first available file descriptor
  `protected AnnotatedEmuSyscallUseropLibrary<T>.StructuredPart`
  `newStructuredPart()`
  Plug our Sleigh-defined syscalls in
  `EmuUnixFileDescriptor<T>`
  `putDescriptor(int fd, EmuUnixFileDescriptor<T> desc)`
  Put a descriptor into the process' open file handles
  `protected EmuUnixFileDescriptor<T>`
  `releaseFd(int fd)`
  Release/invalidate the given file descriptor number
  `protected abstract boolean`
  `returnErrno(PcodeExecutor<T> executor, int errno)`
  Place the errno into the machine as expected by the simulated platform's ABI
  `T`
  `unix_close(T fd)`
  The UNIX `close` system call
  `T`
  `unix_exit(T status)`
  The UNIX `exit` system call
  `void`
  `unix_group_exit(T status)`
  The UNIX `group_exit` system call
  `T`
  `unix_open(PcodeExecutorState<T> state, T pathnamePtr, T flags, T mode)`
  The UNIX `open` system call
  `T`
  `unix_read(PcodeExecutorState<T> state, T fd, T bufPtr, T count)`
  The UNIX `read` system call
  `T`
  `unix_write(PcodeExecutorState<T> state, T fd, T bufPtr, T count)`
  The UNIX `write` system call

  ### Methods inherited from class ghidra.pcode.emu.sys.AnnotatedEmuSyscallUseropLibrary

  `disposeAdditionalArchives, getAdditionalArchives, getSyscalls, getSyscallUserop, mapAndBindSyscalls, mapAndBindSyscalls, newBoundSyscall`

  ### Methods inherited from class ghidra.pcode.exec.AnnotatedPcodeUseropLibrary

  `getMethodLookup, getOperandType, getUserops`

  ### Methods inherited from class java.lang.Object

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

  ### Methods inherited from interface ghidra.pcode.emu.sys.EmuSyscallLibrary

  `readSyscallNumber, syscall`

  ### Methods inherited from interface ghidra.pcode.exec.PcodeUseropLibrary

  `compose, getSymbols, getUserops`

- ## Field Details

  - ### fs

    protected final EmuUnixFileSystem<T> fs

  - ### user

    protected EmuUnixUser user

  - ### intSize

    protected final int intSize

  - ### closedFds

    protected final NavigableSet<Integer> closedFds

  - ### descriptors

    protected final Map<Integer,EmuUnixFileDescriptor<T>> descriptors

- ## Constructor Details

  - ### AbstractEmuUnixSyscallUseropLibrary

    public AbstractEmuUnixSyscallUseropLibrary(PcodeMachine<T> machine, EmuUnixFileSystem<T> fs, Program program)
    Construct a new library
    Parameters:
      `machine` - the machine emulating the hardware
      `fs` - the file system to export to the user-space program
      `program` - a program containing the syscall definitions and conventions, likely the target program

  - ### AbstractEmuUnixSyscallUseropLibrary

    public AbstractEmuUnixSyscallUseropLibrary(PcodeMachine<T> machine, EmuUnixFileSystem<T> fs, Program program, EmuUnixUser user)
    Construct a new library
    Parameters:
      `machine` - the machine emulating the hardware
      `fs` - a file system to export to the user-space program
      `program` - a program containing the syscall definitions and conventions, likely the target program
      `user` - the "current user" to simulate

- ## Method Details

  - ### lowestFd

    protected int lowestFd()
    Get the first available file descriptor
    Returns:
      the lowest available descriptor

  - ### claimFd

    protected int claimFd(EmuUnixFileDescriptor<T> desc)
    Claim the lowest available file descriptor number for the given descriptor object

    The descriptor will be added to the descriptor table for the claimed number

    Parameters:
      `desc` - the descriptor object
    Returns:
      the descriptor number

  - ### findFd

    protected EmuUnixFileDescriptor<T> findFd(int fd)
    Get the file descriptor object for the given file descriptor number
    Parameters:
      `fd` - the descriptor number
    Returns:
      the descriptor object
    Throws:
      `EmuUnixException` - with `AbstractEmuUnixSyscallUseropLibrary.Errno.EBADF` if the file descriptor is invalid

  - ### releaseFd

    protected EmuUnixFileDescriptor<T> releaseFd(int fd)
    Release/invalidate the given file descriptor number
    Parameters:
      `fd` - the file descriptor number
    Returns:
      the removed descriptor object
    Throws:
      `EmuUnixException` - with `AbstractEmuUnixSyscallUseropLibrary.Errno.EBADF` if the file descriptor is invalid

  - ### newStructuredPart

    protected AnnotatedEmuSyscallUseropLibrary<T>.StructuredPart newStructuredPart()
    Plug our Sleigh-defined syscalls in
    Overrides:
      `newStructuredPart` in class `AnnotatedEmuSyscallUseropLibrary<T>`
    Returns:
      the structured part

  - ### convertFlags

    protected abstract Set<EmuUnixFileSystem.OpenFlag> convertFlags(int flags)
    Convert the flags as defined for this platform to flags understood by the simulator
    Parameters:
      `flags` - the platform-defined flags
    Returns:
      the simulator-defined flags

  - ### createHandle

    protected EmuUnixFileDescriptor<T> createHandle(EmuUnixFile<T> file, int flags)
    A factory method for creating an open file handle
    Parameters:
      `file` - the file opened by the handle
      `flags` - the open flags, as specified by the user, as defined by the platform
    Returns:
      the handle

  - ### getErrno

    protected abstract int getErrno(AbstractEmuUnixSyscallUseropLibrary.Errno err)
    Get the platform-specific errno value for the given simulator-defined errno
    Parameters:
      `err` - the simulator-defined errno
    Returns:
      the platform-defined errno

  - ### putDescriptor

    public EmuUnixFileDescriptor<T> putDescriptor(int fd, EmuUnixFileDescriptor<T> desc)
    Put a descriptor into the process' open file handles
    Parameters:
      `fd` - the file descriptor value
      `desc` - the simulated descriptor (handle, console, etc.)
    Returns:
      the previous descriptor, which probably ought to be `null`

  - ### returnErrno

    protected abstract boolean returnErrno(PcodeExecutor<T> executor, int errno)
    Place the errno into the machine as expected by the simulated platform's ABI
    Parameters:
      `executor` - the executor for the thread running this system call
      `errno` - the error number
    Returns:
      true if the errno was successfully placed

  - ### handleError

    public boolean handleError(PcodeExecutor<T> executor, PcodeExecutionException err)
    Description copied from interface: `EmuSyscallLibrary`
    Try to handle an error, usually by returning it to the user program

    If the particular error was not expected, it is best practice to return false, causing the emulator to interrupt. Otherwise, some state is set in the machine that, by convention, communicates the error back to the user program.

    Parameters:
      `executor` - the executor for the thread that caused the error
      `err` - the error
    Returns:
      true if execution can continue uninterrupted

  - ### unix_exit

    public T unix_exit(T status)
    The UNIX `exit` system call

    This just throws an exception, which the overall simulator or script should catch.

    Parameters:
      `status` - the status code
    Returns:
      never
    Throws:
      `EmuProcessExitedException` - always

  - ### unix_read

    public T unix_read(PcodeExecutorState<T> state, T fd, T bufPtr, T count)
    The UNIX `read` system call
    Parameters:
      `state` - to receive the thread's state
      `fd` - the file descriptor
      `bufPtr` - the pointer to the buffer to receive the data
      `count` - the number of bytes to read
    Returns:
      the number of bytes successfully read

  - ### unix_write

    public T unix_write(PcodeExecutorState<T> state, T fd, T bufPtr, T count)
    The UNIX `write` system call
    Parameters:
      `state` - to receive the thread's state
      `fd` - the file descriptor
      `bufPtr` - the pointer to the buffer of data to write
      `count` - the number of bytes to write
    Returns:
      the number of bytes successfully written

  - ### unix_open

    public T unix_open(PcodeExecutorState<T> state, T pathnamePtr, T flags, T mode)
    The UNIX `open` system call
    Parameters:
      `state` - to receive the thread's state
      `pathnamePtr` - the file's path (pointer to character string)
      `flags` - the flags
      `mode` - the mode
    Returns:
      the file descriptor

  - ### unix_close

    public T unix_close(T fd)
    The UNIX `close` system call
    Parameters:
      `fd` - the file descriptor
    Returns:
      0 for success

  - ### unix_group_exit

    public void unix_group_exit(T status)
    The UNIX `group_exit` system call

    This just throws an exception, which the overall simulator or script should catch.

    Parameters:
      `status` - the status code
    Throws:
      `EmuProcessExitedException` - always