<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Function set "Directory functions" - Function set "Directory functions"</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Function set "Directory functions"</h1>
<p class="faldoc_brief">Directory and file names functions. </p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#dirChange">dirChange()</a></td><td>Changes the current working directory. </td></tr>
<tr><td><a href="#dirCurrent">dirCurrent()</a></td><td>Returns the current working directory. </td></tr>
<tr><td><a href="#dirMake">dirMake()</a></td><td>Creates a directory. </td></tr>
<tr><td><a href="#dirMakeLink">dirMakeLink()</a></td><td>Creates a soft link to a file. </td></tr>
<tr><td><a href="#dirReadLink">dirReadLink()</a></td><td>On systems supporting symbolic links, returns the linked file. </td></tr>
<tr><td><a href="#dirRemove">dirRemove()</a></td><td>Removes an empty directory. </td></tr>
<tr><td><a href="#fileChgroup">fileChgroup()</a></td><td>Changes UNIX group to a directory entry. </td></tr>
<tr><td><a href="#fileChmod">fileChmod()</a></td><td>Changes UNIX access right to a directory entry. </td></tr>
<tr><td><a href="#fileChown">fileChown()</a></td><td>Changes UNIX owner to a directory entry. </td></tr>
<tr><td><a href="#fileCopy">fileCopy()</a></td><td>Copies a whole file from one position to another. </td></tr>
<tr><td><a href="#fileExt">fileExt()</a></td><td>Return the extension in a complete filename. </td></tr>
<tr><td><a href="#fileMove">fileMove()</a></td><td>Renames a file locally. </td></tr>
<tr><td><a href="#fileName">fileName()</a></td><td>Determines the name of a file in a complete path. </td></tr>
<tr><td><a href="#fileNameMerge">fileNameMerge()</a></td><td>Merges a filename split up in four elements. </td></tr>
<tr><td><a href="#filePath">filePath()</a></td><td>Return the path specification part in a complete filename. </td></tr>
<tr><td><a href="#fileRemove">fileRemove()</a></td><td>Removes a file from the system. </td></tr>
<tr><td><a href="#fileType">fileType()</a></td><td>Deterimnes the type of a file. </td></tr>
<tr><td><a href="#fileUnit">fileUnit()</a></td><td>Return the unit specificator in a complete filename. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Directory and file names functions. </p>
<p class="faldoc_text">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. </p>
<h2 class="faldoc_title">Members</h2>
<h3 class="faldoc_funcname"><a name="dirChange">dirChange()</a></h3>
<p class="item_brief">Changes the current working directory. </p>
<p class="faldoc_funcdecl">dirChange( newDir )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">newDir</td><td class="faldoc_paramdesc">The new working directory. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirCurrent">dirCurrent()</a></h3>
<p class="item_brief">Returns the current working directory. </p>
<p class="faldoc_funcdecl">dirCurrent</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A string representing the current working directory. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirMake">dirMake()</a></h3>
<p class="item_brief">Creates a directory. </p>
<p class="faldoc_funcdecl">dirMake( dirname, [bFull] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dirname</td><td class="faldoc_paramdesc">The name of the directory to be created. </td></tr>
<tr><td class="faldoc_optparam">bFull</td><td class="faldoc_optparamdesc">Create also the full pat to the given directory. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">On success, this function creates the given directory with normal attributes. </p>
<p class="faldoc_text">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: </p>
<pre class="faldoc_code">
dirMake( "top/middle/bottom" )
</pre>
<p class="faldoc_text"> instructs <b>dirMake</b> to create the directory bottom in a subdirectory "middle", which should already exist. Passing <b>true</b> as second parameter, dirMake will also try to create directories leading to the final destination, if they are missing. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirMakeLink">dirMakeLink()</a></h3>
<p class="item_brief">Creates a soft link to a file. </p>
<p class="faldoc_funcdecl">dirMakeLink( source, dest )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">source</td><td class="faldoc_paramdesc">The original file path. </td></tr><tr><td class="faldoc_param">dest</td><td class="faldoc_paramdesc">The path to the link file. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text">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. </p>
<p class="faldoc_text">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). </p>
</p>
<h3 class="faldoc_funcname"><a name="dirReadLink">dirReadLink()</a></h3>
<p class="item_brief">On systems supporting symbolic links, returns the linked file. </p>
<p class="faldoc_funcdecl">dirReadLink( linkPath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">linkPath</td><td class="faldoc_paramdesc">A path to a symbolic link. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="dirRemove">dirRemove()</a></h3>
<p class="item_brief">Removes an empty directory. </p>
<p class="faldoc_funcdecl">dirRemove( dir )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">dir</td><td class="faldoc_paramdesc">The path to the directory to be removed. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function removes an empty directory. On failure an IoError with code 1012 will be raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileChgroup">fileChgroup()</a></h3>
<p class="item_brief">Changes UNIX group to a directory entry. </p>
<p class="faldoc_funcdecl">fileChgroup( path, groupId )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">A file or otherwise valid directory entry. </td></tr><tr><td class="faldoc_param">groupId</td><td class="faldoc_paramdesc">The new group id. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function changes the group ownership of the given file on POSIX systems. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileChmod">fileChmod()</a></h3>
<p class="item_brief">Changes UNIX access right to a directory entry. </p>
<p class="faldoc_funcdecl">fileChmod( path, mode )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">A file or otherwise valid directory entry. </td></tr><tr><td class="faldoc_param">mode</td><td class="faldoc_paramdesc">The new access mode. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileChown">fileChown()</a></h3>
<p class="item_brief">Changes UNIX owner to a directory entry. </p>
<p class="faldoc_funcdecl">fileChown( path, ownerId )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">A file or otherwise valid directory entry. </td></tr><tr><td class="faldoc_param">ownerId</td><td class="faldoc_paramdesc">The new ownerId. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function changes the user ownership of the given file on POSIX systems. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileCopy">fileCopy()</a></h3>
<p class="item_brief">Copies a whole file from one position to another. </p>
<p class="faldoc_funcdecl">fileCopy( source, dest )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">source</td><td class="faldoc_paramdesc">Source file to be copied </td></tr><tr><td class="faldoc_param">dest</td><td class="faldoc_paramdesc">Destination file. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function performs a file copy. The function is still experimental and needs addition of VM interruption protocol compliancy, as well as the possibility to preserve or change the system attributes in the target copy. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileExt">fileExt()</a></h3>
<p class="item_brief">Return the extension in a complete filename. </p>
<p class="faldoc_funcdecl">fileExt( fullpath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fullpath</td><td class="faldoc_paramdesc">A string containing a path. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The extension part. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The function determines the element past a dot after the filename part. Filenames can start with a "."; they are not considered extensions. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The filename should be in Falcon format (URI convention with forward slashes). </p>
</p>
<h3 class="faldoc_funcname"><a name="fileMove">fileMove()</a></h3>
<p class="item_brief">Renames a file locally. </p>
<p class="faldoc_funcdecl">fileMove( sourcePath, destPath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">sourcePath</td><td class="faldoc_paramdesc">The path of the file to be moved. </td></tr><tr><td class="faldoc_param">destPath</td><td class="faldoc_paramdesc">The path of the destination file. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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). </p>
<p class="faldoc_text">On failure, an IoError is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileName">fileName()</a></h3>
<p class="item_brief">Determines the name of a file in a complete path. </p>
<p class="faldoc_funcdecl">fileName( path )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">A string containing a path. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The filename part in the path. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileNameMerge">fileNameMerge()</a></h3>
<p class="item_brief">Merges a filename split up in four elements. </p>
<p class="faldoc_funcdecl">fileNameMerge( spec, path, filename, ext )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">spec</td><td class="faldoc_paramdesc">The disk or server specification, an array containing all the elements of the file path, or nil. </td></tr><tr><td class="faldoc_param">path</td><td class="faldoc_paramdesc">Path to the file, or nil. </td></tr><tr><td class="faldoc_param">filename</td><td class="faldoc_paramdesc">Filename, or nil. </td></tr><tr><td class="faldoc_param">ext</td><td class="faldoc_paramdesc">extension, or nil. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A complete absolute path. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text"> It is also possible to pass all the four elements in an array, in place of the <b>spec</b> parameter. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function is an interal shortcut to the <a href="./class_Path.html">Path</a> class. </p>
</p>
<h3 class="faldoc_funcname"><a name="filePath">filePath()</a></h3>
<p class="item_brief">Return the path specification part in a complete filename. </p>
<p class="faldoc_funcdecl">filePath( fullpath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fullpath</td><td class="faldoc_paramdesc">A string containing a path. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The path part. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> The filename should be in Falcon format (URI convention with forward slashes). </p>
</p>
<h3 class="faldoc_funcname"><a name="fileRemove">fileRemove()</a></h3>
<p class="item_brief">Removes a file from the system. </p>
<p class="faldoc_funcdecl">fileRemove( filename )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">filename</td><td class="faldoc_paramdesc">The name, relative or absolute path of the file to be removed. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_IoError.html">IoError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function tries to remove a file from the filesystem. If unsuccessful, an error with code 1015 is raised. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileType">fileType()</a></h3>
<p class="item_brief">Deterimnes the type of a file. </p>
<p class="faldoc_funcdecl">fileType( filename )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">filename</td><td class="faldoc_paramdesc">Relative or absolute path to a file. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A valid file type or FileStat.NOTFOUND if not found. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">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. </p>
<p class="faldoc_text">Returned values may be: </p>
<ul>
<li>FileStat.NORMAL </li><li>FileStat.DIR </li><li>FileStat.PIPE </li><li>FileStat.LINK </li><li>FileStat.DEVICE </li><li>FileStat.SOCKET </li><li>FileStat.UNKNOWN </li>
</ul>
<p class="faldoc_text">or FileStat.NOTFOUND if the file doesn't exist. </p>
</p>
<h3 class="faldoc_funcname"><a name="fileUnit">fileUnit()</a></h3>
<p class="item_brief">Return the unit specificator in a complete filename. </p>
<p class="faldoc_funcdecl">fileUnit( fullpath )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">fullpath</td><td class="faldoc_paramdesc">A string containing a path. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The unit specificator part. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the unit specification in a complete path. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
