# Class `nixio.fs`

Low-level and high-level filesystem manipulation library.

## Functions

access (path, mode1, ...) | Check user's permission on a file.
basename (path) | Strip the directory part from a path.
chmod (path, mode) | Change the file mode.
chown (path, user, group) | (POSIX) Change owner and group of a file.
copy (src, dest) | Copy a file, directory or symlink non-recursively preserving file mode, timestamps, owner and group.
copyr (src, dest) | Copy a file, directory or symlink recursively preserving file mode, timestamps, owner and group.
datacopy (src, dest, limit) | Copy data between files.
dir (path) | Iterate over the entries of a directory.
dirname (path) | Strip the base from a path.
glob (pattern) | (POSIX) Find pathnames matching a pattern.
lchown (path, user, group) | (POSIX) Change owner and group of a file and do not resolve if target is a symlink.
link (oldpath, newpath) | Create a hard link.
lstat (path, field) | Get file status and attributes and do not resolve if target is a symlink.
mkdir (path, mode) | Create a new directory.
mkdirr (dest, mode) | Create a directory and all needed parent directories recursively.
mkfifo (path, mode) | (POSIX) Create a FIFO (named pipe).
move (src, dest) | Rename a file, directory or symlink non-recursively across filesystems.
mover (src, dest) | Rename a file, directory or symlink recursively across filesystems.
readfile (path, limit) | Read the contents of a file into a buffer.
readlink (path) | (POSIX) Read the target of a symbolic link.
realpath (path) | Return the cannonicalized absolute pathname.
remove (path) | Remove a file or directory.
rename (src, dest) | Renames a file or directory.
rmdir (path) | Remove an empty directory.
stat (path, field) | Get file status and attributes.
statvfs (path) | (POSIX) Get filesystem statistics.
symlink (oldpath, newpath) | (POSIX) Create a symbolic link.
unlink (path) | Delete a name and - if no links are left - the associated file.
utimes (path, actime, mtime) | Change file last access and last modification time.
writefile (path, data) | Write a buffer into a file truncating the file first.

## Functions

access (path, mode1, ...)
  Check user's permission on a file.

  ### Parameters

  - path: Path
  - mode1: First Mode to check ["f", "r", "w", "x"]
  - ...: More Modes to check [-"-]

  ### Return value:

  true
basename (path)
  Strip the directory part from a path.

  ### Parameters

  - path: Path

  ### Usage:

  This function cannot fail and will never return nil.

  ### Return value:

  basename
chmod (path, mode)
  Change the file mode.

  ### Parameters

  - path: Path
  - mode: File mode [decimal mode number, "[-r][-w][-xsS][-r][-w][-xsS][-r][-w][-xtT]"]

  ### Usage

  - Windows only supports setting the write-protection through the "Writable to others" bit.
  - Notice: The mode-flag for the functions open, mkdir, mkfifo are affected by the umask.

  ### Return value:

  true

  ### See also:

  - umask
chown (path, user, group)
  (POSIX) Change owner and group of a file.

  ### Parameters

  - path: Path
  - user: User ID or Username (optional)
  - group: Group ID or Groupname (optional)

  ### Return value:

  true
copy (src, dest)
  Copy a file, directory or symlink non-recursively preserving file mode, timestamps, owner and group.

  ### Parameters

  - src: Source path
  - dest: Destination path

  ### Usage:

  The destination must always be a full destination path e.g. do not omit the basename even if source and destination basename are equal.

  ### Return value:

  true
copyr (src, dest)
  Copy a file, directory or symlink recursively preserving file mode, timestamps, owner and group.

  ### Parameters

  - src: Source path
  - dest: Destination path

  ### Usage:

  The destination must always be a full destination path e.g. do not omit the basename even if source and destination basename are equal.

  ### Return value:

  true
datacopy (src, dest, limit)
  Copy data between files.

  ### Parameters

  - src: Source file path
  - dest: Destination file path
  - limit: Maximum bytes to copy (optional)

  ### Return value:

  true
dir (path)
  Iterate over the entries of a directory.

  ### Parameters

  - path: Path

  ### Usage:

  The special entries "." and ".." are omitted.

  ### Return value:

  directory iterator returning one entry per call
dirname (path)
  Strip the base from a path.

  ### Parameters

  - path: Path

  ### Usage:

  This function cannot fail and will never return nil.

  ### Return value:

  dirname
glob (pattern)
  (POSIX) Find pathnames matching a pattern.

  ### Parameters

  - pattern: Pattern

  ### Return values:

  1. path iterator
  2. number of matches
lchown (path, user, group)
  (POSIX) Change owner and group of a file and do not resolve if target is a symlink.

  ### Parameters

  - path: Path
  - user: User ID or Username (optional)
  - group: Group ID or Groupname (optional)

  ### Return value:

  true
link (oldpath, newpath)
  Create a hard link.

  ### Parameters

  - oldpath: Path
  - newpath: Path

  ### Usage:

  This function calls link() on POSIX and CreateHardLink() on Windows.

  ### Return value:

  true
lstat (path, field)
  Get file status and attributes and do not resolve if target is a symlink.

  ### Parameters

  - path: Path
  - field: Only return a specific field, not the whole table (optional)

  ### Return value:

  Table containing attributes (see stat for a detailed description)

  ### See also:

  - stat
mkdir (path, mode)
  Create a new directory.

  ### Parameters

  - path: Path
  - mode: File mode (optional, see chmod and umask)

  ### Return value:

  true

  ### See also:

  - chmod
  - umask
mkdirr (dest, mode)
  Create a directory and all needed parent directories recursively.

  ### Parameters

  - dest: Destination path
  - mode: File mode (optional, see chmod and umask)

  ### Return value:

  true

  ### See also:

  - chmod
  - umask
mkfifo (path, mode)
  (POSIX) Create a FIFO (named pipe).

  ### Parameters

  - path: Path
  - mode: File mode (optional, see chmod and umask)

  ### Return value:

  true

  ### See also:

  - chmod
  - umask
move (src, dest)
  Rename a file, directory or symlink non-recursively across filesystems.

  ### Parameters

  - src: Source path
  - dest: Destination path

  ### Usage:

  The destination must always be a full destination path e.g. do not omit the basename even if source and destination basename are equal.

  ### Return value:

  true
mover (src, dest)
  Rename a file, directory or symlink recursively across filesystems.

  ### Parameters

  - src: Source path
  - dest: Destination path

  ### Usage:

  The destination must always be a full destination path e.g. do not omit the basename even if source and destination basename are equal.

  ### Return value:

  true
readfile (path, limit)
  Read the contents of a file into a buffer.

  ### Parameters

  - path: Path
  - limit: Maximum bytes to read (optional)

  ### Return value:

  file contents
readlink (path)
  (POSIX) Read the target of a symbolic link.

  ### Parameters

  - path: Path

  ### Return value:

  target path
realpath (path)
  Return the cannonicalized absolute pathname.

  ### Parameters

  - path: Path

  ### Return value:

  absolute path
remove (path)
  Remove a file or directory.

  ### Parameters

  - path: Path

  ### Return value:

  true
rename (src, dest)
  Renames a file or directory.

  ### Parameters

  - src: Source path
  - dest: Destination path

  ### Usage:

  It is normally not possible to rename files across fileystems.

  ### Return value:

  true
rmdir (path)
  Remove an empty directory.

  ### Parameters

  - path: Path

  ### Return value:

  true
stat (path, field)
  Get file status and attributes.

  ### Parameters

  - path: Path
  - field: Only return a specific field, not the whole table (optional)

  ### Return value:

  Table containing:
  - atime = Last access timestamp
  - blksize = Blocksize (POSIX only)
  - blocks = Blocks used (POSIX only)
  - ctime = Creation timestamp
  - dev = Device ID
  - gid = Group ID
  - ino = Inode
  - modedec = Mode converted into a decimal number
  - modestr = Mode as string as returned by `ls -l`
  - mtime = Last modification timestamp
  - nlink = Number of links
  - rdev = Device ID (if special file)
  - size = Size in bytes
  - type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]
  - uid = User ID
statvfs (path)
  (POSIX) Get filesystem statistics.

  ### Parameters

  - path: Path to any file within the filesystem.

  ### Return value:

  Table containing:
  - bavail = available blocks
  - bfree = free blocks
  - blocks = number of fragments
  - frsize = fragment size
  - favail = available inodes
  - ffree = free inodes
  - files = inodes
  - flag = flags
  - fsid = filesystem ID
  - namemax = maximum filename length
symlink (oldpath, newpath)
  (POSIX) Create a symbolic link.

  ### Parameters

  - oldpath: Path
  - newpath: Path

  ### Return value:

  true
unlink (path)
  Delete a name and - if no links are left - the associated file.

  ### Parameters

  - path: Path

  ### Return value:

  true
utimes (path, actime, mtime)
  Change file last access and last modification time.

  ### Parameters

  - path: Path
  - actime: Last access timestamp (optional, default: current time)
  - mtime: Last modification timestamp (optional, default: actime)

  ### Return value:

  true
writefile (path, data)
  Write a buffer into a file truncating the file first.

  ### Parameters

  - path: Path
  - data: Data to write

  ### Return value:

  true