Seed7 provides a portable access to the services provided by an operating system. This interface is oriented towards POSIX and UNIX.

A portable access to the contents of directories in the file system is provided. For example: After the declaration

    var array string: dir_array is 0 times "";

the following statement

    dir_array := read_dir(".");

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;

Note that the strings contain only the name of the file. Additional information must be obtained by other calls. Other directories can be read by using their name in the 'read_dir' call. Basing on this mechanism another mechanism is constructed to read the contents of a directory as file. This is shown in the following example

    ...

    include "dir.s7i";

    var file: dir_file is STD_NULL;
    var string: file_name is "";

    ...

    dir_file := open_dir(".");
    file_name := getln(dir_file);
    while file_name <> "" do
      writeln(file_name);
      file_name := getln(dir_file);
    end while;

This is useful in programs that accept a list of filenames as input. Using the 'open_dir' mechanism it is possible to read the filenames directly from a directory without large changes in the program.

In most operating systems each process has a current working directory. With the following statement

    my_dir := getcwd();

the full path of the current working directory is assigned to the string variable 'my_dir'. To change the current working directory the next statement can be used

    chdir("/usr/bin");

A new directory can be created with

    mkdir("my_dir");

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. Therefore 'fileType' never returns 'FILE_SYMLINK'. The function 'fileTypeSL' does not follow symbolic links. Therefore 'fileTypeSL' can also return 'FILE_SYMLINK'. Most functions which use a file path except 'fileTypeSL' and 'readlink' follow symbolic links.

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' is not representable in the system path type.

FILE_ERROR

The system function returns an error other than ENOENT.

The permissions of a file can determined with 'fileMode':

      const func fileMode: fileMode (in string: filePath) is ...

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' is not representable in the system path type.

FILE_ERROR

A system function returns an error.

The permissions of a file can changed with 'setFileMode':

      const proc: setFileMode (in string: filePath, in fileMode: newFileMode) is ...

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' is not representable in the system path type.

FILE_ERROR

A system function returns an error.

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

Returns:

For directorys 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' is not representable in the system path type.

RANGE_ERROR

The file size is not representable as integer.

FILE_ERROR

It was not possible to determine the file size.

The access time of a file is returned by the function 'getATime':

      const func time: getATime (in string: filePath) is ...

Possible exceptions:

MEMORY_ERROR

Not enough memory to convert 'filePath' to the system path type.

RANGE_ERROR

'filePath' is not representable in the system path type.

FILE_ERROR

A system function returns an error.

The change time of a file is returned by the function 'getCTime':

      const func time: getCTime (in string: filePath) is ...

Possible exceptions:

MEMORY_ERROR

Not enough memory to convert 'filePath' to the system path type.

RANGE_ERROR

'filePath' is not representable in the system path type.

FILE_ERROR

A system function returns an error.

The modification time of a file is returned by the function 'getMTime':

      const func time: getMTime (in string: filePath) is ...

Possible exceptions:

MEMORY_ERROR

Not enough memory to convert 'filePath' to the system path type.

RANGE_ERROR

'filePath' is not representable in the system path type.

FILE_ERROR

A system function returns an error.

The function 'setATime' sets the access time of a file:

      const proc: setATime (in string: filePath, in time: aTime) is ...

Possible exceptions:

MEMORY_ERROR

Not enough memory to convert 'filePath' to the system path type.

RANGE_ERROR

'filePath' is not representable in the system path type.

FILE_ERROR

A system function returns an error.

The function 'setMTime' sets the modification time of a file:

      const proc: setMTime (in string: filePath, in time: aTime) is ...

Possible exceptions:

MEMORY_ERROR

Not enough memory to convert 'filePath' to the system path type.

RANGE_ERROR

'filePath' is not representable in the system path type.

FILE_ERROR

A system function returns an error.

The function 'readlink' reads the destination of a symbolic link:

      const func string: readlink (in string: filePath) is ...

Returns:

The symbolic link refered 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' is not representable in the system path type.

FILE_ERROR

The file described with 'filePath' does not exist or is not a symbolic link.

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

Name of the symbolic link to be created.

dest

String to be contained in the symbolic link.

Possible exceptions:

MEMORY_ERROR

Not enough memory to convert 'source' or 'dest' to the system path type.

RANGE_ERROR

'source' or 'dest' is not representable in the system path type.

FILE_ERROR

A system function returns an error.

The function 'removeFile' removes a file or empty directory:

      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' is not representable in the system path type.

FILE_ERROR

The file does not exist or a system function returns an error.

The function 'removeAnyFile' removes a file independend of its file type:

      const proc: removeAnyFile (in string: filePath) is ...

Possible exceptions:

MEMORY_ERROR

Not enough memory to convert 'filePath' to the system path type.

RANGE_ERROR

'filePath' is not representable in the system path type.

FILE_ERROR

The file does not exist or a system function returns an error.

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 undependend 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 the 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' is not representable in the system path type.

FILE_ERROR

Source file does not exist, destination file already exists or a system function returns an error.

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 the 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' is not representable in the system path type.

FILE_ERROR

Source file does not exist, destination file already exists or a system function returns an error.

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' is not representable in the system path type.

FILE_ERROR

Source file does not exist, destination file already exists or a system function returns an error.

The function 'argv(PROGRAM)' returns the argument vector of the program as array of strings.

      const func array string: argv (PROGRAM) is ...

Returns:

An array of strings containing the argument vector.

The function 'getenv' determines the value of an environment variable.

      const func string: getenv (in string: name) is ...

The 'getenv' function 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.