NAME

lfs - file system operations (LuaFileSystem)

OVERVIEW

LuaFileSystem is a Lua (http://www.lua.org) 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.

It was developed for Lua 5.0. Version 1.2 follows the package model (http://www.keplerproject.org/compat) for Lua 5.1 (see section Installation for more details).

EXAMPLES

Directory iterator

The following example iterates over a directory and recursively lists the attributes for each file inside it.

  require"lfs"
  
  function attrdir (path)
      for file in lfs.dir(path) do
          if file ~= "." and file ~= ".." then
              local f = path..'/'..file
              print ("\t "..f)
              local attr = lfs.attributes (f)
              assert (type(attr) == "table")
              if attr.mode == "directory" then
                  attrdir (f)
              else
                  for name, value in pairs(attr) do
                      print (name, value)
                  end
              end
          end
      end
  end
  
  attrdir (".")

DOWNLOAD

LuaFileSystem source can be downloaded from its Lua Forge (http://luaforge.net/projects/luafilesystem/files) page. If you are using LuaBinaries (http://luabinaries.luaforge.net) Release 2 a Windows binary version of LuaFileSystem can also be found at the LuaForge page.

INSTALLATION

LuaFileSystem follows the package model (http://www.keplerproject.org/compat/) for Lua 5.1, therefore it should be ``installed''. Refer to Compat-5.1 configuration section about how to install the compiled binary properly. The compiled binary should be copied to a directory in your LUA_CPATH.

Windows users can use the binary version of LuaFileSystem (lfs.dll) available at LuaForge (http://luaforge.net/projects/luafilesystem/files).

REFERENCE

LuaFileSystem offers the following functions:

`lfs.attributes`

  lfs.attributes (filepath [, aname])

Returns a table with the file attributes corresponding to filepath (or nil followed by an error message in case of error). If the second optional argument is given, then only the value of the named attribute is returned (this use is equivalent to lfs.attributes(filepath).aname, but the table is not created and only one attribute is retrieved from the O.S.). 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
blocks: block allocated for file; (Unix only)
blksize: optimal file system I/O blocksize; (Unix only)

`lfs.chdir`

  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`

  lfs.currentdir ()

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

`lfs.dir`

  lfs.dir (path)

Lua iterator over the entries of a given directory. Each time the iterator is called it returns a string with an entry of the directory; nil is returned when there is no more entries. Raises an error if path is not a directory.

`lfs.lock`

  lfs.lock (filehandle, mode[, start[, length]])</code>

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.