LuaFileSystem

Introduction

LuaFileSystem is a Lua library developed to complement the set of functions related to file systems offered by the standard Lua distribution.

LuaFileSystem offers a portable way to access the underlying directory structure and file attributes.

Installation

LuaFileSystem is distributed as a pair of C source and header files. The distribution provides a Makefile prepared to compile the library and install it. The file config should be edited to suit the needs of the aimed platform.

LuaFileSystem follows the package proposal for Lua 5.1, therefore this package should be "installed". In other words, if you are using Lua 5.0, the files compat-5.1.c and compat-5.1.h must be used in the compilation and the file compat-5.1.lua must be installed in the LUA_PATH. If you are using Lua 5.1, nothing should be done.

Reference

LuaFileSystem offers the following functions:

lfs.attributes (filepath)

Returns a table with the file attributes corresponding to filepath. The attributes are:

dev: on Unix systems, represents the device that the inode resides on. On Windows systems, represents the drive number of the disk containing the file.
ino: on Unix systems, represents the inode number. On Windows systems this has no meaning.
mode: string representing the associated protection mode (the values could be file, directory, link, socket, named pipe, char device, block device or other)
nlink: number of hard links to the file
uid: user-id of owner
gid: group-id of owner
rdev: on Unix systems, represents the device type, for special file inode. On Windows systems represents the same as dev.
access: time of last access
modification: time of last data modification
change: time of last file status change
size: file size, in bytes
blocks: block allocated for file; (Unix only)
blksize: optimal file system I/O blocksize; (Unix only)

lfs.chdir (path)

Changes the current working directory to the given path.
Returns true in case of success or nil plus an error string.

lfs.currentdir ()

Returns a string with the current working directory or nil plus an error string.

lfs.dir (path)

Lua iterator over the entries of a given directory. Raises an error if path is not a directory.

lfs.lock (filehandle, mode[, start[, length]])

Locks a file or a part of it. This function works on open files; the file handle should be specified as the first argument. The string mode could be either r (for a read/shared lock) or w (for a write/exclusive lock). The optional arguments start and length can be used to specify a starting point and its length; both should be numbers.
Returns a boolean indicating if the operation was successful; in case of error, it returns false plus an error string.

lfs.mkdir (dirname)

Creates a new directory. The argument is the name of the new directory.
Returns a boolean indicating whether the operation succeeds or not (in this case, an error string is returned too).

lfs.touch (filepath [, atime [, mtime]])

Set access and modification times of a file. This function is a bind to utime function. The first argument is the filename, the second argument (atime) is the access time, and the third argument (mtime) is the modification time. Both times are provided in seconds (which should be generated with Lua standard function os.date). If the modifition time is omitted, the access time provided is used; if both times are omitted, the current time is used.
Returns a boolean indicating whether the operation succeeded or not (followed by an error string when it fails).

lfs.unlock (filehandle[, start[, length]])

Unlocks a file or a part of it. This function works on open files; the file handle should be specified as the first argument. The optional arguments start and length can be used to specify a starting point and its length; both should be numbers.
Returns a boolean indicating if the operation was successful; in case of error, it returns false plus a string describing the error.