# Module `posix.sys.stat`

File Status Querying and Setting.

## Functions

S_ISBLK (mode) | Test for a block special file.
S_ISCHR (mode) | Test for a character special file.
S_ISDIR (mode) | Test for a directory.
S_ISFIFO (mode) | Test for a fifo special file.
S_ISLNK (mode) | Test for a symbolic link.
S_ISREG (mode) | Test for a regular file.
S_ISSOCK (mode) | Test for a socket.
chmod (path, mode) | Change the mode of the path.
fstat (fd) | Information about a file descriptor.
lstat (path) | Information about an existing file path.
mkdir (path[, mode=511]) | Make a directory.
mkfifo (path[, mode=511]) | Make a FIFO pipe.
stat (path) | Information about an existing file path.
umask (mode) | Set file mode creation mask.

## Tables

PosixStat | File state record.

## Constants

posix.sys.stat | Stat constants.

## Functions

S_ISBLK (mode)
  Test for a block special file.

  ### Parameters:

  - mode int the st_mode field of a PosixStat

  ### Returns:

  int non-zero if mode represents a block special file
S_ISCHR (mode)
  Test for a character special file.

  ### Parameters:

  - mode int the st_mode field of a PosixStat

  ### Returns:

  int non-zero if mode represents a character special file
S_ISDIR (mode)
  Test for a directory.

  ### Parameters:

  - mode int the st_mode field of a PosixStat

  ### Returns:

  int non-zero if mode represents a directory
S_ISFIFO (mode)
  Test for a fifo special file.

  ### Parameters:

  - mode int the st_mode field of a PosixStat

  ### Returns:

  int non-zero if mode represents a fifo special file
S_ISLNK (mode)
  Test for a symbolic link.

  ### Parameters:

  - mode int the st_mode field of a PosixStat

  ### Returns:

  int non-zero if mode represents a symbolic link
S_ISREG (mode)
  Test for a regular file.

  ### Parameters:

  - mode int the st_mode field of a PosixStat

  ### Returns:

  int non-zero if mode represents a regular file
S_ISSOCK (mode)
  Test for a socket.

  ### Parameters:

  - mode int the st_mode field of a PosixStat

  ### Returns:

  int non-zero if mode represents a socket
chmod (path, mode)
  Change the mode of the path.

  ### Parameters:

  - path string existing file path to act on
  - mode int access modes to set for path

  ### Returns:

  int `0`, if successful

  ### Or

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

  ### See also:

  chmod(2)

  ### Usage:

      local sys_stat = require "posix.sys.stat"
      sys_stat.chmod ('bin/dof', bit.bor (sys_stat.S_IRWXU, sys_stat.S_IRGRP))

fstat (fd)
  Information about a file descriptor.

  ### Parameters:

  - fd int file descriptor to act on

  ### Returns:

  PosixStat information about fd, if successful

  ### Or

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

  ### See also:

  - fstat(2)

  ### Usage:

      local fcntl = require "posix.fcntl"
      local sys_stat = require "posix.sys.stat"
      local fd = assert(fcntl.open("/etc/hostname", fcntl.O_RDONLY))
      for a, b in pairs (sys_stat.fstat(fd)) do print (a, b) end

lstat (path)
  Information about an existing file path. If file is a symbolic link, return information about the link itself.

  ### Parameters:

  - path string file to act on

  ### Returns:

  PosixStat information about path, if successful

  ### Or

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

  ### See also:

  - lstat(2)

  ### Usage:

      local sys_stat = require "posix.sys.stat"
      for a, b in pairs (sys_stat.lstat "/etc/") do print (a, b) end

mkdir (path[, mode=511])
  Make a directory.

  ### Parameters:

  - path string location in file system to create directory
  - mode int access modes to set for path (default 511)

  ### Returns:

  int `0`, if successful

  ### Or

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

  ### See also:

  mkdir(2)
mkfifo (path[, mode=511])
  Make a FIFO pipe.

  ### Parameters:

  - path string location in file system to create fifo
  - mode int access modes to set for path (default 511)

  ### Returns:

  int file descriptor for path, if successful

  ### Or

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

  ### See also:

  mkfifo(2)
stat (path)
  Information about an existing file path. If file is a symbolic link, return information about the file the link points to.

  ### Parameters:

  - path string file to act on

  ### Returns:

  PosixStat information about path, if successful

  ### Or

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

  ### See also:

  - stat(2)
  - lstat

  ### Usage:

      local sys_stat = require "posix.sys.stat"
      for a, b in pairs (sys_stat.stat "/etc/") do print (a, b) end

umask (mode)
  Set file mode creation mask.

  ### Parameters:

  - mode int new file creation mask

  ### Returns:

  int previous umask

  ### See also:

  - umask(2)
  - posix.umask

## Tables

PosixStat
  File state record.

  ### Fields:

  - st_dev int device id
  - st_ino int inode number
  - st_mode int mode of file
  - st_nlink int number of hardlinks to file
  - st_uid int user id of file owner
  - st_gid int group id of file owner
  - st_rdev int additional device specific id for special files
  - st_size int file size in bytes
  - st_atime int time of last access
  - st_mtime int time of last data modification
  - st_ctime int time of last state change
  - st_blksize int preferred block size
  - st_blocks int number of blocks allocated

## Constants

posix.sys.stat
  Stat constants. Any constants not available in the underlying system will be `nil` valued.

  ### Fields:

  - S_IFMT int file type mode bitmask
  - S_IFBLK int block special
  - S_IFCHR int character special
  - S_IFDIR int directory
  - S_IFIFO int fifo
  - S_IFLNK int symbolic link
  - S_IFREG int regular file
  - S_IFSOCK int socket
  - S_IRWXU int user read, write and execute
  - S_IRUSR int user read
  - S_IWUSR int user write
  - S_IXUSR int user execute
  - S_IRWXG int group read, write and execute
  - S_IRGRP int group read
  - S_IWGRP int group write
  - S_IXGRP int group execute
  - S_IRWXO int other read, write and execute
  - S_IROTH int other read
  - S_IWOTH int other write
  - S_IXOTH int other execute
  - S_ISGID int set group id on execution
  - S_ISUID int set user id on execution

  ### Usage:

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

generated by LDoc 1.5.0 Last updated 2023-06-16 20:19:12