
--- 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.

module "lfs"

--- 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 (http://www.lua.org/manual/5.0/manual.html#5.7).
function attributes (filepath, aname)

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

--- Returns a string with the current working directory or nil
--  plus an error string.
function currentdir ()

---    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.
function dir (path)

--- 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.
function lock (filehandle, mode, start, length)

--- Creates a new directory. The argument is the name of the new
--    directory.
--    Returns true if the operation was successful;
--    in case of error, it returns nil plus an error string.
function mkdir (dirname)

--- Removes an existing directory. The argument is the name of the directory.
--    Returns true if the operation was successful;
--    in case of error, it returns nil plus an error string.
function rmdir (dirname)

--- 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 modification time is omitted, the access time provided is used;
--    if both times are omitted, the current time is used.
--    Returns true if the operation was successful;
--    in case of error, it returns nil plus an error string.
function touch (filepath, atime, mtime)

--- 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.
function unlock (filehandle, start, length)
