# Module `posix.fcntl`

File Control.

Low-level control over file descriptors, including creating new file descriptors with `open`.

## Functions

fcntl (fd, cmd[, arg=0]) | Manipulate file descriptor.
open (path, oflags[, mode=511]) | Open a file.
posix_fadvise (fd, offset, len, advice) | Instruct kernel on appropriate cache behaviour for a file or file segment.

## Tables

flock | Advisory file locks.

## Constants

posix.fcntl | Fcntl constants.

## Functions

fcntl (fd, cmd[, arg=0])
  Manipulate file descriptor.

  ### Parameters:

  - fd int file descriptor to act on
  - cmd int operation to perform
  - arg int or flock when cmd is `F_GETLK`, `F_SETLK` or `F_SETLKW`, then arg is a flock table, otherwise an integer with meaning dependent upon the value of cmd. (default 0)

  ### Returns:

  integer return value depending on cmd, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  - fcntl(2)
  - lock.lua

  ### Usage:

      local flag = posix.fcntl (fd, posix.F_GETFL)

open (path, oflags[, mode=511])
  Open a file.

  ### Parameters:

  - path string
  - oflags int bitwise OR of zero or more of `O_RDONLY`, `O_WRONLY`, `O_RDWR`, `O_APPEND`, `O_CREAT`, `O_DSYNC`, `O_EXCL`, `O_NOCTTY`, `O_NONBLOCK`, `O_RSYNC`, `O_SYNC` and `O_TRUNC` (and `O_CLOEXEC`, where supported)
  - mode int access modes used by `O_CREAT` (default 511)

  ### Returns:

  int file descriptor for path, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  open(2)

  ### Usage:

      local P = require "posix.fcntl"
      fd = P.open ("data", bit.bor (P.O_CREAT, P.O_RDWR), bit.bor (P.S_IRWXU, P.S_IRGRP))

posix_fadvise (fd, offset, len, advice)
  Instruct kernel on appropriate cache behaviour for a file or file segment.

  ### Parameters:

  - fd int open file descriptor
  - offset int start of region
  - len int number of bytes in region
  - advice int one of `POSIX_FADV_NORMAL`, `POSIX_FADV_SEQUENTIAL`, `POSIX_FADV_RANDOM`, `POSIX_FADV_NOREUSE`, `POSIX_FADV_WILLNEED` or `POSIX_FADV_DONTNEED`

  ### Returns:

  int `0`, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum

  ### See also:

  posix_fadvise(2)

## Tables

flock
  Advisory file locks. Passed as arg to fcntl when cmd is `F_GETLK`, `F_SETLK` or `F_SETLKW`.

  ### Fields:

  - l_start int starting offset
  - l_len int len = 0 means until end of file
  - l_pid int lock owner
  - l_type int lock type
  - l_whence int one of `SEEK_SET`, `SEEK_CUR` or `SEEK_END`

## Constants

posix.fcntl
  Fcntl constants. Any constants not available in the underlying system will be `0` valued, if they are usually bitwise ORed with other values, otherwise `nil`.

  ### Fields:

  - AT_EACCESS int test access permitted for effective IDs, not real IDs
  - AT_FDCWD int indicate *at functions to use current directory
  - AT_REMOVEDIR int remove directory instead of unlinking file
  - AT_SYMLINK_FOLLOW int follow symbolic links
  - AT_SYMLINK_NOFOLLOW int do not follow symbolic links
  - FD_CLOEXEC int close file descriptor on exec flag
  - F_DUPFD int duplicate file descriptor
  - F_GETFD int get file descriptor flags
  - F_SETFD int set file descriptor flags
  - F_GETFL int get file status flags
  - F_SETFL int set file status flags
  - F_GETLK int get record locking information
  - F_SETLK int set record locking information
  - F_SETLKW int set lock, and wait if blocked
  - F_GETOWN int get SIGIO/SIGURG process owner
  - F_SETOWN int set SIGIO/SIGURG process owner
  - F_RDLCK int shared or read lock
  - F_WRLCK int exclusive or write lock
  - F_UNLCK int unlock
  - O_RDONLY int open for reading only
  - O_WRONLY int open for writing only
  - O_RDWR int open for reading and writing
  - O_APPEND int set append mode
  - O_CLOEXEC int set FD_CLOEXEC atomically
  - O_CREAT int create if nonexistent
  - O_DSYNC int synchronise io data integrity
  - O_EXCL int error if file already exists
  - O_NOCTTY int don't assign controlling terminal
  - O_NONBLOCK int no delay
  - O_RSYNC int synchronise file read integrity
  - O_SYNC int synchronise file write integrity
  - O_TRUNC int truncate to zero length
  - POSIX_FADV_NORMAL int no advice
  - POSIX_FADV_SEQUENTIAL int expecting to access data sequentially
  - POSIX_FADV_RANDOM int expecting to access data randomly
  - POSIX_FADV_NOREUSE int expecting to access data once only
  - POSIX_FADV_WILLNEED int expecting to access data in the near future
  - POSIX_FADV_DONTNEED int not expecting to access the data in the near future

  ### Usage:

      -- Print fcntl constants supported on this host.
      for name, value in pairs (require "posix.fcntl") do
        if type (value) == "number" then
          print (name, value)
         end
      end

generated by LDoc 1.5.0 Last updated 2025-02-16 13:16:41