=head1 NAME

lfs - file system operations (LuaFileSystem)

=head1 OVERVIEW

LuaFileSystem is a Lua (L<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
(L<http://www.keplerproject.org/compat>) for Lua 5.1 (see section
Installation for more details).

=head1 EXAMPLES

=head2 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 (".")

=head1 DOWNLOAD

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

=head1 INSTALLATION

LuaFileSystem follows the package model
(L<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 C<LUA_CPATH>.

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

=head1 REFERENCE

LuaFileSystem offers the following functions:

=head2 C<lfs.attributes>

  lfs.attributes (filepath [, aname])

Returns a table with the file attributes corresponding to C<filepath>
(or C<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
C<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 C<mode> is a string, all the others
are numbers, and the time related attributes use the same time
reference of C<os.time>:

=over 4

=item 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

=item ino

on Unix systems, this represents the inode number. On Windows systems
this has no meaning

=item mode

string representing the associated protection mode (the values could
be C<file>, C<directory>, C<link>, C<socket>, C<named pipe>, C<char
device>, C<block device> or C<other>)

=item nlink

number of hard links to the file

=item uid

user-id of owner (Unix only, always 0 on Windows)

=item gid

group-id of owner (Unix only, always 0 on Windows)

=item rdev

on Unix systems, represents the device type, for special file inodes.
On Windows systems represents the same as C<dev>

=item access

time of last access

=item modification

time of last data modification

=item change

time of last file status change

=item size

file size, in bytes

=item blocks

block allocated for file; (Unix only)

=item blksize

optimal file system I/O blocksize; (Unix only)

=back

=head2 C<lfs.chdir>

  lfs.chdir (path)

Changes the current working directory to the given C<path>.

Returns C<true> in case of success or C<nil> plus an error string.

=head2 C<lfs.currentdir>

  lfs.currentdir ()

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

=head2 C<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;
C<nil> is returned when there is no more entries.  Raises an error if
C<path> is not a directory.

=head2 C<lfs.lock>

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

Locks a file or a part of it. This function works on I<open files>;
the file handle should be specified as the first argument.  The string
C<mode> could be either C<r> (for a read/shared lock) or C<w> (for a
write/exclusive lock). The optional arguments C<start> and C<length>
can be used to specify a starting point and its length; both should be
numbers.

Returns C<true> if the operation was successful; in case of error, it
returns C<nil> plus an error string.

=head2 C<lfs.mkdir>

  lfs.mkdir (dirname)

Creates a new directory. The argument is the name of the new
directory.

Returns C<true> if the operation was successful; in case of error, it
returns C<nil> plus an error string.

=head2 C<lfs.rmdir>

  lfs.rmdir (dirname)

Removes an existing directory. The argument is the name of the
directory.

Returns C<true> if the operation was successful; in case of error, it
returns C<nil> plus an error string.

=head2 C<lfs.touch>

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

Set access and modification times of a file. This function is a bind
to C<utime> function. The first argument is the filename, the second
argument (C<atime>) is the access time, and the third argument
(C<mtime>) is the modification time.  Both times are provided in
seconds (which should be generated with Lua standard function
C<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 C<true> if the operation was successful; in case of error, it
returns C<nil> plus an error string.

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

Unlocks a file or a part of it. This function works on I<open files>;
the file handle should be specified as the first argument. The
optional arguments C<start> and C<length> can be used to specify a
starting point and its length; both should be numbers.

Returns C<true> if the operation was successful; in case of error, it
returns C<nil> plus an error string.

=head1 CONTACT

For more information please contact us
(info-NO-SPAM-THANKS@keplerproject.org).  Comments are welcome!

You can also reach other Kepler developers and users on the Kepler
Project mailing list (L<http://luaforge.net/mail/?group_id=104>).

=head1 HISTORY

=over 4

=item Version 1.2 [15/Mar/2006]


  - added optional argument to C<lfs.attributes>
  - added function C<lfs.rmdir>
  - bug correction on C<lfs.dir>

=item Version 1.1 [30/May/2005] (L<http://www.keplerproject.org/luafilesystem/1.1/>)

  - added function C<lfs.touch>.

=item Version 1.0 [21/Jan/2005] (L<http://www.keplerproject.org/luafilesystem/1.0/>)

=item Version 1.0 Beta [10/Nov/2004]

=back

=head1 VERSION

This is version 1.2.

=head1 CREDITS

LuaFileSystem was designed by Roberto Ierusalimschy, AndrE<eacute>
Carregal and TomE<aacute>s Guisasola as part of the Kepler Project
(L<http://www.keplerproject.org>), which holds its copyright.

=head1 LICENSE

LuaFileSystem is free software: it can be used for both academic and
commercial purposes at absolutely no cost. There are no royalties or
GNU-like "copyleft" restrictions. LuaFileSystem qualifies as Open
Source (L<http://www.opensource.org/docs/definition.html>) software.
Its licenses are compatible with GPL
(L<http://www.gnu.org/licenses/gpl.html>).  LuaFileSystem is not in
the public domain and the Kepler Project
(L<http://www.keplerproject.org>) keep its copyright.  The legal
details are below.

The spirit of the license is that you are free to use
LuaFileSystem for any purpose at no cost without having to ask us.
The only requirement is that if you do use LuaFileSystem, then you
should give us credit by including the appropriate copyright notice
somewhere in your product or its documentation.

The LuaFileSystem library is designed and implemented by Roberto
Ierusalimschy, AndrE<eacute> Carregal and TomE<aacute>s Guisasola.
The implementation is not derived from licensed software.

Copyright E<copy> 2004-2006 The Kepler Project.

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy,
modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.