Module nixio.fs

Low-level and high-level filesystem manipulation library.

Functions

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


Functions

nixio.fs.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
nixio.fs.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
nixio.fs.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:

nixio.fs.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
nixio.fs.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
nixio.fs.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
nixio.fs.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
nixio.fs.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
nixio.fs.dirname (path)
Strip the base from a path.

Parameters

  • path: Path

Usage:

This function cannot fail and will never return nil.

Return value:

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

Parameters

  • pattern: Pattern

Return values:

  1. path iterator
  2. number of matches
nixio.fs.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
nixio.fs.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
nixio.fs.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:

nixio.fs.mkdir (path, mode)
Create a new directory.

Parameters

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

Return value:

true

See also:

nixio.fs.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:

nixio.fs.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:

nixio.fs.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
nixio.fs.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
nixio.fs.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
nixio.fs.readlink (path)
(POSIX) Read the target of a symbolic link.

Parameters

  • path: Path

Return value:

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

Parameters

  • path: Path

Return value:

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

Parameters

  • path: Path

Return value:

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

Parameters

  • src: Source path
  • dest: Destination path

Usage:

It is normally not possible to rename files accross fileystems.

Return value:

true
nixio.fs.rmdir (path)
Remove an empty directory.

Parameters

  • path: Path

Return value:

true
nixio.fs.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
nixio.fs.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
nixio.fs.symlink (oldpath, newpath)
(POSIX) Create a symbolic link.

Parameters

  • oldpath: Path
  • newpath: Path

Return value:

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

Parameters

  • path: Path

Return value:

true
nixio.fs.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
nixio.fs.writefile (path, data)
Write a buffer into a file truncating the file first.

Parameters

  • path: Path
  • data: Data to write

Return value:

true

Valid XHTML 1.0!