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.

+ +

Building

+ +

+LuaFileSystem should be built with Lua 5.1 so the language library +and header files for the target version must be installed properly. +

+ +

+LuaFileSystem offers a Makefile and a separate configuration file, +config, +which should be edited to suit your installation before running +make. +The file has some definitions like paths to the external libraries, +compiler options and the like. +

+ +

On Windows, the C runtime used to compile LuaFileSystem must be the same +runtime that Lua uses, or some LuaFileSystem functions will not work.

+ +

Installation

+ +

The easiest way to install LuaFileSystem is to use LuaRocks:

+ +

+luarocks install luafilesystem
+

+ +

If you prefer to install LuaFileSystem manually, the compiled binary should be copied to a directory in your +C path.

+ +

Reference

+ +

+LuaFileSystem offers the following functions: +

+ +

lfs.attributes (filepath [, request_name | result_table])

Returns a table with the file attributes corresponding to + filepath (or nil followed by an error message and a system-dependent error code + in case of error). + If the second optional argument is given and is a string, then only the value of the + named attribute is returned (this use is equivalent to + lfs.attributes(filepath)[request_name], but the table is not created + and only one attribute is retrieved from the O.S.). + if a table is passed as the second argument, it (result_table) is filled with attributes and returned instead of a new table. + The attributes are described as follows; + attribute mode is a string, all the others are numbers, + and the time related attributes use the same time reference of + os.time: +

dev: on Unix systems, this 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, this 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 (Unix only, always 0 on Windows)
gid: group-id of owner (Unix only, always 0 on Windows)
rdev: on Unix systems, represents the device type, for special file inodes. + 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
permissions: file permissions string
blocks: block allocated for file; (Unix only)
blksize: optimal file system I/O blocksize; (Unix only)

+ This function uses stat internally thus if the given + filepath is a symbolic link, it is followed (if it points to + another link the chain is followed recursively) and the information + is about the file it refers to. + To obtain information about the link itself, see function + lfs.symlinkattributes. +

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.lock_dir(path, [seconds_stale])

Creates a lockfile (called lockfile.lfs) in path if it does not + exist and returns the lock. If the lock already exists checks if + it's stale, using the second parameter (default for the second + parameter is INT_MAX, which in practice means the lock will never + be stale. To free the the lock call lock:free().
+ In case of any errors it returns nil and the error message. In + particular, if the lock exists and is not stale it returns the + "File exists" message.

lfs.currentdir ()

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

iter, dir_obj = lfs.dir (path)

+ Lua iterator over the entries of a given directory. + Each time the iterator is called with dir_obj it returns a directory entry's name as a string, or + nil if there are no more entries. You can also iterate by calling dir_obj:next(), and + explicitly close the directory before the iteration finished with dir_obj:close(). + 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 true if the operation was successful; in + case of error, it returns nil plus an error string. +

lfs.link (old, new[, symlink])

Creates a link. The first argument is the object to link to + and the second is the name of the link. If the optional third + argument is true, the link will by a symbolic link (by default, a + hard link is created). +

lfs.mkdir (dirname)

Creates a new directory. The argument is the name of the new + directory.
+ Returns true in case of success or nil, an error message and + a system-dependent error code in case of error. +

lfs.rmdir (dirname)

Removes an existing directory. The argument is the name of the directory.
+ Returns true in case of success or nil, an error message and + a system-dependent error code in case of error. + +

lfs.setmode (file, mode)

Sets the writing mode for a file. The mode string can be either "binary" or "text". + Returns true followed the previous mode string for the file, or + nil followed by an error string in case of errors. + On non-Windows platforms, where the two modes are identical, + setting the mode has no effect, and the mode is always returned as binary. +

lfs.symlinkattributes (filepath [, request_name])

Identical to lfs.attributes except that + it obtains information about the link itself (not the file it refers to). + It also adds a target field, containing + the file name that the symlink points to. + On Windows this function does not yet support links, and is identical to + lfs.attributes. +

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.time). + If the modification time is omitted, the access time provided is used; + if both times are omitted, the current time is used.
+ Returns true in case of success or nil, an error message and + a system-dependent error code in case of error. +

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 true if the operation was successful; + in case of error, it returns nil plus an error string. +

+ +