Seed7 FAQ Manual Programs Examples Libraries Algorithms Benchmarks Index Download GitHub Build Seed7 Links
Manual Introduction Tutorial Declarations Statements Types Parameters Objects File I/O Syntax Tokens Expressions OS access Database Graphic Actions Foreign funcs Errors
OS access standard path file properties fileType fileSize getFileMode setFileMode getATime setATime getCTime getMTime setMTime getOwner setOwner getGroup setGroup symbolic links readLink finalPath symlink directories readDir openDir getcwd chdir mkdir homeDir removeFile removeTree copyFile cloneFile moveFile argv program name program path program dir program file getenv setenv unsetenv environment
Manual
OS access
 previous   up   next 

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:

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
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

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 symlink

The function symlink creates a symbolic link called 'dest' that contains the string referred by 'source': 

const proc: symlink (in string: source, in string: dest) is ...

Parameters:

source
String to be contained in the symbolic link.
dest
Name of the symbolic link to be created.

Possible exceptions:

MEMORY_ERROR
Not enough memory to convert 'source' or 'dest' to the system path type.
RANGE_ERROR
'source' or 'dest' does not use the standard path representation, or one of them cannot be converted to the system path type.
FILE_ERROR
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.

Examples:

...

include "dir.s7i";

var file: aDirFile is STD_NULL;
var string: fileName is "";

...

aDirFile := openDir(".");
fileName := getln(aDirFile);
while fileName <> "" do
  writeln(fileName);
  fileName := getln(aDirFile);
end while;

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 mkdir

The function mkdir creates a new directory. 

const proc: mkdir (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 

mkdir("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.
 previous   up   next