Manual |
|
OS access |
|
12. OPERATING SYSTEM ACCESS
Seed7 provides a portable access to the services provided by an operating system. This interface is oriented towards Posix and Unix. The functions in this chapter are defined in the libraries "osfiles.s7i", "dir.s7i" and "environment.s7i".
12.1 Standard path representation
A path specifies the location of a file in a file system. Operating systems have different concepts how a path should look like. Seed7 compensates this differences with a standard path representation. Standard paths are used by all Seed7 functions dealing with paths. The standard path representation uses strings with the following properties to describe paths:
- The slash ('/') is used as path delimiter.
- Drive letters are not allowed, but there is a solution to replace them.
- Except for the path "/" a standard path is not allowed to end with a slash.
When a function like open is called with a path that is not "/", but ends with a slash, the exception RANGE_ERROR is raised. Under Windows a standard path like "/c" is mapped to the drive "C:". Reading the directory "/" under Windows returns a list of available drives. A path with a backslash or with a drive letter may raise the exception RANGE_ERROR, when a function like open is called.
An absolute path specifies an unique location in the file system. Absolute paths always start with a slash. A relative path specifies a location relative to the current working directory of the program. Although standard paths are defined in a portable way, an absolute path will usually not be portable.
12.2 File properties
Files have properties like type, size, mode (permissions), several timestamps, owner and group. Properties like type and size cannot be changed directly. Other properties may be changed. For these properties getters and setters are provided.
Property Getter Setter Comment file type fileType
fileTypeSLFor possible values see function fileType
Among others FILE_REGULAR and FILE_DIR are file typessize fileSize
bigFileSizeThe size of a file in bytes mode getFileMode setFileMode Permissions. For possible values see function getFileMode aTime getATime setATime Time of last access cTime getCTime Time of last status change mTime getMTime setMTime Time of last modification of content owner getOwner setOwner The user name of the file owner group getGroup setGroup The name of the group the file belongs to
12.2.1 fileType
The type of a file can determined with fileType or fileTypeSL:
const func integer: fileType (in string: filePath) is ... const func integer: fileTypeSL (in string: filePath) is ...
The function fileType does follow symbolic links. The function fileTypeSL does not follow symbolic links. A return value of FILE_ABSENT does not imply that a file with this name can be created, since missing directories and invalid file names will also cause FILE_ABSENT.
Returns:
- FILE_ABSENT
- A component of path does not exist.
- FILE_UNKNOWN
- The file exists but has an unknown type.
- FILE_REGULAR
- The file is a regular file.
- FILE_DIR
- The file is a directory.
- FILE_CHAR
- The file is a character special file.
- FILE_BLOCK
- The file is a block special file.
- FILE_FIFO
- The file is a pipe or FIFO special file.
- FILE_SYMLINK
- The file is a symbolic link.
- FILE_SOCKET
- The file is a socket.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation.
- FILE_ERROR
- The system function returns an error other than ENOENT, ENOTDIR, ENAMETOOLONG or EACCES.
12.2.2 fileSize
The size of a file can be determined with fileSize and bigFileSize:
const func integer: fileSize (in string: filePath) is ... const func bigInteger: bigFileSize (in string: filePath) is ...
The functions follow symbolic links.
Returns:
For directories a size of 0 is returned. For other file types the operating system functions 'stat()' and 'seek()' are used to determine the size of a file. The functions fileSize and bigFileSize succeed when at least one strategy to determine the file size succeeds.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- RANGE_ERROR
- The file size is not representable as integer (this exception is not raised by bigFileSize).
- FILE_ERROR
- It was not possible to determine the file size.
12.2.3 getFileMode
The file mode (permissions) of a file can determined with getFileMode:
const func fileMode: getFileMode (in string: filePath) is ...
The function follows symbolic links. The type fileMode is defined as 'set of filePermission'.
Returns:
The fileMode which is defined as set of filePermission.
The literal values of filePermission are:
- EXEC_OTHER
- others have execute permission
- WRITE_OTHER
- others have write permission
- READ_OTHER
- others have read permission
- EXEC_GROUP
- group has execute permission
- WRITE_GROUP
- group has write permission
- READ_GROUP
- group has read permission
- EXEC_USER
- owner has execute permission
- WRITE_USER
- owner has write permission
- READ_USER
- owner has read permission
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation, or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.4 setFileMode
The permissions of a file can be changed with setFileMode:
const proc: setFileMode (in string: filePath, in fileMode: newFileMode) is ...
The function follows symbolic links. The type fileMode is defined as 'set of filePermission'.
The literal values of filePermission are:
- EXEC_OTHER
- others have execute permission
- WRITE_OTHER
- others have write permission
- READ_OTHER
- others have read permission
- EXEC_GROUP
- group has execute permission
- WRITE_GROUP
- group has write permission
- READ_GROUP
- group has read permission
- EXEC_USER
- owner has execute permission
- WRITE_USER
- owner has write permission
- READ_USER
- owner has read permission
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.5 getATime
The access time of a file is returned by the function getATime:
const func time: getATime (in string: filePath) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.6 setATime
The function setATime sets the access time of a file:
const proc: setATime (in string: filePath, in time: aTime) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type, or 'aTime' is invalid, or 'aTime' cannot be converted to the system file time.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.7 getCTime
The status change time of a file is returned by the function getCTime:
const func time: getCTime (in string: filePath) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.8 getMTime
The modification time of a file is returned by the function getMTime:
const func time: getMTime (in string: filePath) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.9 setMTime
The function setMTime sets the modification time of a file:
const proc: setMTime (in string: filePath, in time: aTime) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type or 'aTime' is invalid, or 'aTime' cannot be converted to the system file time.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.10 getOwner
The owner of a file is returned by the function getOwner:
const func string: getOwner (in string: filePath) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.11 setOwner
The function setOwner sets the owner of a file:
const proc: setOwner (in string: filePath, in string: owner) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type or 'aTime' is invalid, or 'aTime' cannot be converted to the system file time.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.12 getGroup
The group of a file is returned by the function getGroup:
const func string: getGroup (in string: filePath) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.2.13 setGroup
The function setGroup sets the group of a file:
const proc: setGroup (in string: filePath, in string: group) is ...
The function follows symbolic links.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type or 'aTime' is invalid, or 'aTime' cannot be converted to the system file time.
- FILE_ERROR
- The file described with 'filePath' does not exist, or a system function returns an error.
12.3 Symbolic links
Symbolic links (symlinks) are files pointing to a target file or directory. They specify a relative or absolute path to the target (destination). Relative symbolic links are relative to their location in the file system and not relative to the current working directory. The target of a symbolic link may not exist. In this case it is a dangling symbolic link. Many file functions follow symbolic links. Following means: For a symbolic link the function follows the symbolic link chain until the path is not a symbolic link again. Afterwards the function is applied to this final path.
Functions that follow symlinks Functions that work only on symlinks and don't follow them A dangling symlink raises FILE_ERROR. FILE_ERROR is raised if 'path' is not a symlink. fileSize(path) bigFileSize(path) getFileMode(path) setFileMode(path, mode) getFileMode(path, SYMLINK) getATime(path) setATime(path, time) getATime(path, SYMLINK) getCTime(path) getMTime(path) setMTime(path, time) getMTime(path, SYMLINK) setMTime(path, time, SYMLINK) getOwner(path) setOwner(path, name) getOwner(path, SYMLINK) setOwner(path, name, SYMLINK) getGroup(path) setGroup(path, name) getGroup(path, SYMLINK) setGroup(path, name, SYMLINK) readLink(path) readLink(path, ABSOLUTE)
Functions that do not follow symbolic links:
Function Comment removeFile(path) Can be used to remove a symbolic link removeTree(path) Can be used to remove a symbolic link cloneFile(source, dest) Can be used to copy a symbolic link moveFile(source, dest) Can be used to rename a symbolic link
12.3.1 readLink
The functions readLink(path) and readLink(path, ABSOLUTE) read the destination of a symbolic link:
const func string: readLink (in string: filePath) is ... const func string: readLink (in string: filePath, ABSOLUTE) is ...
The function readLink(path) reads the link destination stored in the file system. Symbolic links can be relative or absolute. Relative symbolic links are relative to their location in the file system and not relative to the current working directory. The function readLink(path, ABSOLUTE) always returns an absolute path. It leaves absolute symbolic links unchanged and converts relative symbolic links to an absolute path.
Returns:
The symbolic link referred by 'filePath'.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type or not enough memory to represent the result string.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.3.2 finalPath
The function finalPath returns the final path that functions like getMTime and open would use. If filePath is not a symbolic link it is returned. For a symbolic link the function follows the symbolic link chain until the path is not a symbolic link again. The final path may refer to a non-existing file.
const func string: finalPath (in string: filePath) is ...
Parameters:
- filePath
- Relative or absolute path.
Returns:
The final path after possibly following a symbolic link chain.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type or not enough memory to represent the result string.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist or a system function returns an error.
12.3.3 makeLink
The function makeLink creates a symbolic link at symlinkPath that contains the string referred by targetPath. The function does not follow symbolic links.
const proc: makeLink (in string: symlinkPath, in string: targetPath) is ...
Parameters:
- symlinkPath
- Name of the symbolic link to be created.
- targetPath
- String to be contained in the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'symlinkPath' or 'targetPath' to the system path type.
- RANGE_ERROR
- 'symlinkPath' or 'targetPath' does not use the standard path representation, or one of them cannot be converted to the system path type.
- FILE_ERROR
- The file ''dirPath'' already exists, or a system function returns an error.
12.3.4 Symbolic link getFileMode
The file mode (permissions) of a symbolic link can determined with getFileMode(path, SYMLINK):
const func fileMode: getFileMode (in string: filePath, SYMLINK) is ...
The function only works for symbolic links and does not follow the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation, or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.3.5 Symbolic link getATime
The access time of a symbolic link is returned by the function getATime(path, SYMLINK):
const func time: getATime (in string: filePath, SYMLINK) is ...
The function only works for symbolic links and does not follow the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation, or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.3.6 Symbolic link getMTime
The modification time of a symbolic link is returned by the function getMTime(path, SYMLINK):
const func time: getMTime (in string: filePath, SYMLINK) is ...
The function only works for symbolic links and does not follow the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation, or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.3.7 Symbolic link setMTime
The function setMTime(path, time, SYMLINK) sets the modification time of a symbolic link:
const proc: setMTime (in string: filePath, in time: aTime, SYMLINK) is ...
The function only works for symbolic links and does not follow the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type or 'aTime' is invalid, or 'aTime' cannot be converted to the system file time.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.3.8 Symbolic link getOwner
The owner of a symbolic link is returned by the function getOwner(path, SYMLINK):
const func string: getOwner (in string: filePath, SYMLINK) is ...
The function only works for symbolic links and does not follow the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.3.9 Symbolic link setOwner
The function setOwner(path, owner, SYMLINK) sets the owner of a symbolic link:
const proc: setOwner (in string: filePath, in string: owner, SYMLINK) is ...
The function only works for symbolic links and does not follow the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type or 'aTime' is invalid, or 'aTime' cannot be converted to the system file time.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.3.10 Symbolic link getGroup
The group of a symbolic link is returned by the function getGroup(path, SYMLINK):
const func string: getGroup (in string: filePath, SYMLINK) is ...
The function only works for symbolic links and does not follow the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.3.11 Symbolic link setGroup
The function setGroup(path, group, SYMLINK) sets the group of a symbolic link:
const proc: setGroup (in string: filePath, in string: group, SYMLINK) is ...
The function only works for symbolic links and does not follow the symbolic link.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type or 'aTime' is invalid, or 'aTime' cannot be converted to the system file time.
- FILE_ERROR
- The file described with 'filePath' does not exist, or it is not a symbolic link, or a system function returns an error.
12.4 Directory functions
Directories are a special kind of file. They contain references to other files. Some functions work only on directories (e.g.: readDir) while other functions (e.g.: getMTime) will work on any kind of file. Since directories are files they are not mentioned specifically in the description of such generic functions.
12.4.1 readDir
The function readDir provides a portable access to the contents of directories in the file system. It reads the specified directory and the filenames are stored in the string-array result. The files "." and ".." are excluded from the result. Note that the strings contain only the filenames. Additional information must be obtained using other calls.
const func array string: readDir (in string: dirPath) is ...
Returns:
An array of strings containing the names of all files in the specified directory, except "." and ".."
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'dirPath' to the system path type or not enough memory to represent the result array string.
- RANGE_ERROR
- 'dirPath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file described with 'dirPath' does not exist, or it is not a directory, or a system function returns an error.
Examples:
After the declaration
var array string: dir_array is 0 times "";
the statement
dir_array := readDir(".");
reads the current working directory and stores it into the string-array 'dir_array'. The components of the directory can now be accessed via indexing:
for index range 1 to length(dir_array) do writeln(dir_array[index]); end for;
12.4.2 openDir
The function openDir opens the specified directory as file. Each line in this directory file contains the filename of a file present in the directory. The files "." and ".." are left out from the directory file. Note that only filenames can be read from the directory file. Additional information must be obtained with other calls.
const func file: openDir (in string: dirPath) is ...
Returns:
The directory file of the specified directory.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'dirPath' to the system path type or not enough memory to represent the result array string.
- RANGE_ERROR
- 'dirPath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- A system function returns an error.
12.4.3 getcwd
The function getcwd returns the current working directory of the calling process as absolute path.
const func string: getcwd is ...
Returns:
The absolute path of the current working directory.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to represent the result string.
- FILE_ERROR
- The system function returns an error.
Examples:
The statement
my_dir := getcwd;
assigns the full path of the current working directory to the string variable 'my_dir'.
12.4.4 chdir
The function chdir changes the current working directory of the calling process to the specified directory.
const proc: chdir (in string: name) is ...
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'name' to the system path type.
- RANGE_ERROR
- 'name' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- A system function returns an error.
Examples:
The statement
chdir("/usr/bin");
changes the current working directory to "/usr/bin".
12.4.5 makeDir
The function makeDir creates a new directory. The function does not follow symbolic links.
const proc: makeDir (in string: dirPath) is ...
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'dirPath' to the system path type.
- RANGE_ERROR
- 'dirPath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file ''dirPath'' already exists, or a system function returns an error.
Examples:
The statement
makeDir("my_dir");
creates the directory "my_dir".
12.4.6 homeDir
The function homeDir returns the home directory of the user as absolute path.
const func string: homeDir is ...
This function should be preferred over the use of an environment variable such as $HOME. $HOME is not supported under all operating systems and it is not guaranteed, that it uses the standard path representation.
Returns:
The absolute path of the home directory.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to represent the result string.
- FILE_ERROR
- Not able to determine the home directory.
Examples:
The statement
my_dir := homeDir;
assigns the full path of the home directory to the string variable 'my_dir'.
12.5 Maintenance functions
12.5.1 removeFile
The function removeFile removes a file of any type unless it is a directory that is not empty. An attempt to remove a directory that is not empty triggers FILE_ERROR.
const proc: removeFile (in string: filePath) is ...
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation, or it cannot be converted to the system path type.
- FILE_ERROR
- The file does not exist or a system function returns an error.
12.5.2 removeTree
The function removeTree removes a file of any type inclusive a directory tree:
const proc: removeTree (in string: filePath) is ...
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'filePath' to the system path type.
- RANGE_ERROR
- 'filePath' does not use the standard path representation or it cannot be converted to the system path type.
- FILE_ERROR
- The file does not exist or a system function returns an error.
12.5.3 copyFile
The function copyFile copies a file or directory tree:
const proc: copyFile (in string: sourcePath, in string: destPath) is ...
Permissions/mode, ownership and timestamps of the destination file are determined independent of the corresponding source properties. The destination file gets the permissions/mode defined by umask. The user executing the program is the owner of the destination file. The timestamps of the destination file are set to the current time. Symbolic links in sourcePath are always followed. Therefore copyFile will never create a symbolic link. Note that copyFile does not preserve hard links (they are resolved to distinct files).
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'sourcePath' or 'destPath' to the system path type.
- RANGE_ERROR
- 'sourcePath' or 'destPath' does not use the standard path representation or one of them cannot be converted to the system path type.
- FILE_ERROR
- Source file does not exist, destination file already exists or a system function returns an error.
12.5.4 cloneFile
The function cloneFile clones a file or directory tree:
const proc: cloneFile (in string: sourcePath, in string: destPath) is ...
Permissions/mode, ownership and timestamps of the original are preserved. Symlinks are not followed. Instead the symlink is copied. Note that cloneFile does not preserve hard links (they are resolved to distinct files).
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'sourcePath' or 'destPath' to the system path type.
- RANGE_ERROR
- 'sourcePath' or 'destPath' does not use the standard path representation or one of them cannot be converted to the system path type.
- FILE_ERROR
- Source file does not exist, destination file already exists or a system function returns an error.
12.5.5 moveFile
The function moveFile moves and/or renames a file or directory tree:
const proc: moveFile (in string: sourcePath, in string: destPath) is ...
The function uses the C 'rename()' function. When 'rename()' fails the file (or directory tree) is cloned with cloneFile (which preserves permissions/mode, ownership and timestamps) to the new place and with the new name. When cloneFile succeeds the original file is deleted. When cloneFile fails (no space on device or other reason) all remains of the failed clone are removed. Note that cloneFile works for symbolic links but does not preserve hard links (they are resolved to distinct files).
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'sourcePath' or 'destPath' to the system path type.
- RANGE_ERROR
- 'sourcePath' or 'destPath' does not use the standard path representation or one of them cannot be converted to the system path type.
- FILE_ERROR
- Source file does not exist, destination file already exists or a system function returns an error.
12.6 Environment
12.6.1 argv(PROGRAM)
The function argv(PROGRAM) returns the argument vector of the program as array of strings. The name of the program is not part of the argument vector.
const func array string: argv (PROGRAM) is ...
Returns:
An array of strings containing the argument vector.
12.6.2 name(PROGRAM)
The function name(PROGRAM) returns the name of the program without path and extension. The name returned by name(PROGRAM) is the same for interpreted and compiled programs. The function name(PROGRAM) does not follow symbolic links. It determines, with which name a program was called. When several symbolic links refer to one program name(PROGRAM) returns the name of the symbolic link.
const func string: name (PROGRAM) is ...
Returns:
The name of the program.
12.6.3 path(PROGRAM)
The function path(PROGRAM) returns the absolute path of the program. For an interpreted program this is the absolute path of the source file. For a compiled program this is the absolute path of the executable. The function path(PROGRAM) does follow symbolic links.
const func string: path (PROGRAM) is ...
Returns:
The absolute path of the program.
12.6.4 dir(PROGRAM)
The function dir(PROGRAM) returns the absolute path of the directory containing the program. The function dir(PROGRAM) allows placing configuration data in the directory of the program. dir(PROGRAM) is based on path(PROGRAM).
const func string: dir (PROGRAM) is ...
Returns:
The absolute path of the directory containing the program.
12.6.5 file(PROGRAM)
The function file(PROGRAM) returns the filename of the program without path. file(PROGRAM) is based on path(PROGRAM).
const func string: file (PROGRAM) is ...
Returns:
The filename of the program.
12.6.6 getenv
The function getenv determines the value of an environment variable.
const func string: getenv (in string: name) is ...
The function getenv searches the environment for an environment variable with the given 'name'. When such an environment variable exists the corresponding string value is returned.
Returns:
The value of an environment variable or "" when the requested environment variable does not exist.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'name' to the system string type or not enough memory to represent the result string.
- RANGE_ERROR
- 'name' cannot be converted to the system string type or a system function returns an error.
12.6.7 setenv
The function setenv adds or changes an environment variable.
const proc: setenv (in string: name, in string: value) is ...
The function setenv searches the environment for an environment variable with the given 'name'. When such an environment variable exists the corresponding value is changed to 'value'. When no environment variable with the given 'name' exists a new environment variable 'name' with the value 'value' is created.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'name' or 'value' to the system string type.
- RANGE_ERROR
- 'name' or 'value' cannot be converted to the system string type or a system function returns an error.
12.6.8 unsetenv
The function unsetenv removes an environment variable.
const proc: unsetenv (in string: name) is ...
The function unsetenv searches the environment for an environment variable with the given 'name'. When such an environment variable exists it is removed from the environment. When no environment variable with the given 'name' exists the function succeeds, and the environment is unchanged.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to convert 'name' to the system string type.
- RANGE_ERROR
- 'name' cannot be converted to the system string type or a system function returns an error.
12.6.9 environment
The function environment returns the list of environment variable names as array of strings.
const func array string: environment is ...
Returns:
The list of environment variable names.
Possible exceptions:
- MEMORY_ERROR
- Not enough memory to create the result.
|
|