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".
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:
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.
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 fileTypeSL | For possible values see function fileType Among others FILE_REGULAR and FILE_DIR are file types | |
| size | fileSize bigFileSize | The 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 |
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:
Possible exceptions:
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:
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:
Possible exceptions:
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:
Possible exceptions:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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 |
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:
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:
Returns:
The final path after possibly following a symbolic link chain.
Possible exceptions:
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:
Possible exceptions:
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:
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:
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:
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:
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:
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:
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:
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:
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.
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:
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;
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:
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:
Examples:
The statement
my_dir := getcwd;
assigns the full path of the current working directory to the string variable 'my_dir'.
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:
Examples:
The statement
chdir("/usr/bin");
changes the current working directory to "/usr/bin".
The function makeDir creates a new directory. The function does not follow symbolic links.
const proc: makeDir (in string: dirPath) is ...
Possible exceptions:
Examples:
The statement
makeDir("my_dir");
creates the directory "my_dir".
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:
Examples:
The statement
my_dir := homeDir;
assigns the full path of the home directory to the string variable 'my_dir'.
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:
The function removeTree removes a file of any type inclusive a directory tree:
const proc: removeTree (in string: filePath) is ...
Possible exceptions:
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:
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:
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:
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.
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.
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.
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.
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.
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:
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:
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:
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: