LibCUtil (JNA API)
Description: declaration: package: com.sun.jna.platform.unix, class: LibCUtil

Package com.sun.jna.platform.unix

# Class LibCUtil

java.lang.Object
com.sun.jna.platform.unix.LibCUtil

public class LibCUtil extends Object
Utility class supporting variable-width types in the C Library. Portable code should avoid using `off_t` because it is dependent upon features selected at compile-time. This class provides helper methods that safely avoid these types by using 64-bit mappings when available.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static int`
  `ftruncate(int fd, long length)`
  Causes the regular file referenced by `fd` to be truncated to a size of precisely `length` bytes.
  `static Pointer`
  `mmap(Pointer addr, long length, int prot, int flags, int fd, long offset)`
  Creates a new mapping in the virtual address space of the calling process.
  `static void`
  `require32Bit(long val, String value)`
  Test that a value is 32-bit, throwing a custom exception otherwise

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

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

- ## Method Details

  - ### mmap

    public static Pointer mmap(Pointer addr, long length, int prot, int flags, int fd, long offset)
    Creates a new mapping in the virtual address space of the calling process.
    Parameters:
      `addr` - The starting address for the new mapping.

      If `addr` is NULL, then the kernel chooses the (page-aligned) address at which to create the mapping; this is the most portable method of creating a new mapping. If `addr` is not NULL, then the kernel takes it as a hint about where to place the mapping; on Linux, the kernel will pick a nearby page boundary (but always above or equal to the value specified by `/proc/sys/vm/mmap_min_addr`) and attempt to create the mapping there. If another mapping already exists there, the kernel picks a new address that may or may not depend on the hint. The address of the new mapping is returned as the result of the call.

      `length` - Specifies the length of the mapping (which must be greater than 0).
      `prot` - describes the desired memory protection of the mapping (and must not conflict with the open mode of the file). It is either `PROT_NONE` or the bitwise OR of one or more of `PROT_READ`, `PROT_WRITE`, or `PROT_EXEC`.
      `flags` - determines whether updates to the mapping are visible to other processes mapping the same region, and whether updates are carried through to the underlying file. This behavior is determined by including exactly one of `MAP_SHARED`, `MAP_SHARED_VALIDATE`, or `MAP_PRIVATE`. In addition, 0 or more additional flags can be ORed in `flags`.
      `fd` - The file descriptor for the object to be mapped. After the `mmap()` call has returned, the file descriptor can be closed immediately without invalidating the mapping.
      `offset` - The contents of a file mapping (as opposed to an anonymous mapping), are initialized using `length` bytes starting at offset `offset` in the file (or other object) referred to by the file descriptor, `fd`. `offset` must be a multiple of the page size as returned by `sysconf(_SC_PAGE_SIZE)`.
    Returns:
      On success, returns a pointer to the mapped area. On error, the value `MAP_FAILED` (that is, (void *) -1) is returned, and `errno` is set to indicate the cause of the error.

  - ### ftruncate

    public static int ftruncate(int fd, long length)
    Causes the regular file referenced by `fd` to be truncated to a size of precisely `length` bytes.

    If the file previously was larger than this size, the extra data is lost. If the file previously was shorter, it is extended, and the extended part reads as null bytes ('\0').

    The file must be open for writing

    Parameters:
      `fd` - a file descriptor
      `length` - the number of bytes to truncate or extend the file to
    Returns:
      On success, zero is returned. On error, -1 is returned, and `errno` is set appropriately.

  - ### require32Bit

    public static void require32Bit(long val, String value)
    Test that a value is 32-bit, throwing a custom exception otherwise
    Parameters:
      `val` - The value to test
      `value` - The name of the value, to be inserted in the exception message if not 32-bit
    Throws:
      `IllegalArgumentException` - if `val` is not 32-bit