Directory and file names functions.
Directory functions are currently under development. The general principle is that they should be, where possible, multiplatform and portable, with some extensions working only on specific OSes. Also, the general idea on failure is that they should raise an error when success is expected, and return an error value when failure is likely. However, the behavior of the function listed in this section is subject to sudden change, as the contribution of the community (even if just in form of suggestion) is vital.
Changes the current working directory.
dirChange( newDir )
| newDir | The new working directory. | ||
| Raise |
|
On success, the working directory is changed to the specified one. The path must be indicated in Falcon conventions (forward slashes separating directories). On failure, an IoError is raised.
Returns the current working directory.
dirCurrent()
| Return | A string representing the current working directory. | ||
| Raise |
|
On success, a string containing the current working directory is returned. The path is in Falcon convention (forward slashes). If any system error occurs, an IoError is raised.
Creates a directory.
dirMake( dirname, [bFull] )
| dirname | The name of the directory to be created. | ||
| bFull | Create also the full pat to the given directory. | ||
| Raise |
|
On success, this function creates the given directory with normal attributes.
It is possible to specify both a relative or absolute path; both the relative and absolute path can contain a subtree specification, that is, a set of directories separated by forward slashes, which lead to the directory that should be created. For example:
dirMake( "top/middle/bottom" )
instructs dirMake to create the directory bottom in a subdirectory "middle", which should already exist. Passing true as second parameter, dirMake will also try to create directories leading to the final destination, if they are missing.
Creates a soft link to a file.
dirMakeLink( source, dest )
| source | The original file path. |
| dest | The path to the link file. |
The path of both source and dest parameter is to be expressed in Falcon convention (forward slashes), and can be both relative to the working directory or absolute.
Currently, the function works only on UNIX systems; Windows platforms have recently added this functionality, but they are still not supported by this function at the moment.
On success, the function returns true. On failure, it returns false. In case the function is not supported, it just returns false. (Comments are welcome).
On systems supporting symbolic links, returns the linked file.
dirReadLink( linkPath )
| linkPath | A path to a symbolic link. |
If the target file in the linkPath parameter is a symbolic link and can be read, the return value will be a string containing the file the link is pointing to. Otherwise, the function will return nil. Function will return nil also on system where symbolic links are not supported.
Removes an empty directory.
dirRemove( dir )
| dir | The path to the directory to be removed. | ||
| Raise |
|
The function removes an empty directory. On failure an IoError with code 1012 will be raised.
Changes UNIX group to a directory entry.
fileChgroup( path, groupId )
| path | A file or otherwise valid directory entry. | ||
| groupId | The new group id. | ||
| Raise |
|
This function changes the group ownership of the given file on POSIX systems.
Changes UNIX access right to a directory entry.
fileChmod( path, mode )
| path | A file or otherwise valid directory entry. | ||
| mode | The new access mode. | ||
| Raise |
|
This function will work only on POSIX systems. The file access mode will be set along the octal access right defined by POSIX. See man 3 chmod for details.
Changes UNIX owner to a directory entry.
fileChown( path, ownerId )
| path | A file or otherwise valid directory entry. | ||
| ownerId | The new ownerId. | ||
| Raise |
|
This function changes the user ownership of the given file on POSIX systems.
Return the extension in a complete filename.
fileExt( fullpath )
| fullpath | A string containing a path. |
| Return | The extension part. |
The function determines the element past a dot after the filename part. Filenames can start with a "."; they are not considered extensions.
Note: The filename should be in Falcon format (URI convention with forward slashes).
See also: Path.
Renames a file locally.
fileMove( sourcePath, destPath )
| sourcePath | The path of the file to be moved. | ||
| destPath | The path of the destination file. | ||
| Raise |
|
This function actually renames a file. Usually, it will file if the caller tries to move the file across filesystems (i.e. on different discs).
On failure, an IoError is raised.
Determines the name of a file in a complete path.
fileName( path )
| path | A string containing a path. |
| Return | The filename part in the path. |
The function determines the filename part of a complete path name. The returned filename includes the extension, if present. The filename does not need to represent a file actually existing in the system. If the filename part cannot be determined, an empty string is returned.
Merges a filename split up in four elements.
fileNameMerge( spec, path, filename, ext )
| spec | The disk or server specification, an array containing all the elements of the file path, or nil. |
| path | Path to the file, or nil. |
| filename | Filename, or nil. |
| ext | extension, or nil. |
| Return | A complete absolute path. |
The final path is composed by adding a colon after the disk/server specification, a slash after the path and a dot before the extension.
It is also possible to pass all the four elements in an array, in place of the spec parameter.
Note: This function is an interal shortcut to the Path class.
Return the path specification part in a complete filename.
filePath( fullpath )
| fullpath | A string containing a path. |
| Return | The path part. |
The function determines the filename part of a complete path name. The returned filename includes the host or disk specification, if present. The filename does not need to represent a file actually existing in the system.
Note: The filename should be in Falcon format (URI convention with forward slashes).
See also: Path.
Removes a file from the system.
fileRemove( filename )
| filename | The name, relative or absolute path of the file to be removed. | ||
| Raise |
|
This function tries to remove a file from the filesystem. If unsuccessful, an error with code 1015 is raised.
Determines the type of a file.
fileType( filename, [nf] )
| filename | Relative or absolute path to a file. |
| nf | Don't follow symlinks |
| Return | A valid file type or FileStat.NOTFOUND if not found. |
This function is useful to know what of what kind of system entry is a certain file, or if it exists at all, without paying the overhead for a full FileStat object being instantiated.
Returned values may be:
or FileStat.NOTFOUND if the file doesn't exist.
Return the unit specificator in a complete filename.
fileUnit( fullpath )
| fullpath | A string containing a path. |
| Return | The unit specificator part. |
Returns the unit specification in a complete path.
See also: Path.
See also: Path.