LuaFileSystem-ManPage-LuaRocks.txt

LuaFileSystem.txt

LuaFileSystem - LuaRocks
===============================================================================

iter, dir_obj, [nil] = lfs.dir( path )
    'dir' is a Lua iterator over the entries of a given directory, where 'iter' 
    is the iterator closure, 'dir_obj' is the invariant state, and the control 
    variable initial value is nil.  Error raised if 'path' is not a directory.
    
    Each time the iterator is called, 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()'.  You can explicitly close the directory before 
    the iteration is finished by calling 'dir_obj:close()'.

lfs.chdir ( path )
    Changes the current working directory to the given path.
    Returns 'true' or N+E (nil plus an error string).

lfs.currentdir ()
    Returns a string with the current working directory or N+E.

lfs.mkdir ( dirname )
    Creates a new directory; the argument is the name of the new directory.
    Returns 'true' or N+E+C (nil plus an error string plus a code).

lfs.rmdir ( dirname )
    Removes an existing directory; the argument is the name of the directory.
    Returns true or N+E+C.

lfs.setmode ( file, mode )
    Sets the write mode for a file.  The mode string can be either 'binary' or 
    'text'.  Returns 'true' followed the previous mode string for the file, or 
    N+E.  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.touch ( filepath [, atime [, mtime]] )
    Set access and modification times of a file.  This function is a bind to the 
    'utime' function.  The first argument is the filename, the second argument 
    ('atime') is access time, and the third argument ('mtime') is modification 
    time.  Both times are provided in seconds (which should be generated with 
    the Lua standard function 'os.time()').  If modification time is omitted, 
    the access time provided is used; if both times are omitted, current time 
    is used.  Returns 'true' or N+E+C.

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' can be 
    either 'r' (for a read/shared lock) or 'w' (for a write/exclusive lock).  
    The optional arguments 'start' & 'length' can be used to specify a starting 
    point and its length; both should be numbers.  Returns 'true' or N+E.

lfs.lock_dir( path, [seconds_stale] )
    Creates a lockfile (named '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 it will never go stale.)  To free the the lock, call 
    'lock:free()'.  Returns the lock or N+E.  In particular, if the lock exists 
    and is not stale it returns the "File exists" message.

lfs.unlock ( filehandle[, start[, length]] )
    Unlocks a file or a part of it.  This function works on open files; the 
    file's handle is the first argument.  The optional arguments 'start' and 
    'length' are be used to specify a starting point and its length; both are 
    numbers.  Returns 'true' or N+E.

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 be a symbolic link.  (By default, a hard link is created.)

lfs.symlinkattributes ( filepath [, request_name | result_table] )
    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.attributes ( filepath [, request_name | result_table] )
    Returns a table with the file attributes corresponding to filepath, or  
    returns nil followed by an error message and a system-dependent error code.
    
    If the second optional argument is given and is a string, only the value of 
    the named attribute is returned, rather than a table; this use is equivalent 
    to 'lfs.attributes(filepath)[request_name]', which dereferences the table.
    
    If a table is passed as the second argument (as 'result_table'), that table 
    will be filled with attributes and returned instead of a new table.
    
    This function uses 'stat' internally; if the given filepath is a symbolic 
    link, it is followed (i.e., if it points to another link, the chain is 
    followed recursively).  The information returned is for the file it refers 
    to.  To obtain information about the link itself, refer to the function 
    'lfs.symlinkattributes'.  
    
    The attributes are described as follows; 'attribute mode' is a string, all 
    others are numbers; the time-related attributes use the same time reference 
    as 'os.time()'. 
    
    'dev' - on *nix systems, this represents the device that the inode resides 
            on.  On Windows systems, represents the drive number of the volume 
            containing the file.
        
    'ino' - on *nix systems, this represents the inode number.  On Windows 
            systems this has no meaning.
        
    'mode' - a string representing the associated protection mode; values can be
            'file', 'directory', 'link', 'socket', 'named pipe', 'char device', 
            'block device', or 'other'.
        
    'nlink' - the number of hard links to the file.
    
    'uid' - user-id of the file owner.  (*nix only; always 0 on Windows.)
    
    'gid' - group-id of the file owner.  (*nix only; always 0 on Windows.)
    
    'rdev' - on *nix systems, represents 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' - number of blocks allocated for the file.  (*nix only.)
    
    'blksize' - optimal file system I/O blocksize.  (*nix only.)