osp — Logtalk APIs v3.47.0 documentation

protocol

# `osp`

Portable operating-system access protocol.

Author: Paulo Moura
Version: 1:30:0
Date: 2021-02-20
Compilation flags:
`static`
Dependencies:
(none)
Remarks:

> - Error handling: Predicates that require a file or directory to exist throw an error when that is not the case. But the exact exception term is currently backend Prolog compiler dependent.

Inherited public predicates:
(none)

- Public predicates

  - `pid/1`

  - `shell/2`

  - `shell/1`

  - `is_absolute_file_name/1`

  - `absolute_file_name/2`

  - `decompose_file_name/3`

  - `decompose_file_name/4`

  - `path_concat/3`

  - `make_directory/1`

  - `make_directory_path/1`

  - `delete_directory/1`

  - `change_directory/1`

  - `working_directory/1`

  - `temporary_directory/1`

  - `null_device_path/1`

  - `directory_files/2`

  - `directory_files/3`

  - `directory_exists/1`

  - `ensure_directory/1`

  - `file_exists/1`

  - `file_modification_time/2`

  - `file_size/2`

  - `file_permission/2`

  - `rename_file/2`

  - `delete_file/1`

  - `ensure_file/1`

  - `environment_variable/2`

  - `time_stamp/1`

  - `date_time/7`

  - `cpu_time/1`

  - `wall_time/1`

  - `operating_system_type/1`

  - `command_line_arguments/1`

  - `sleep/1`

- Protected predicates

- Private predicates

- Operators

## Public predicates

### `pid/1`

Returns the process identifier of the running process.

Compilation flags:
`static`
Template:
`pid(PID)`
Mode and number of proofs:
`pid(-integer)` - `one`

### `shell/2`

Runs an operating-system shell command and returns its exit status.

Compilation flags:
`static`
Template:
`shell(Command,Status)`
Mode and number of proofs:
`shell(+atom,-integer)` - `one`

### `shell/1`

Runs an operating-system shell command.

Compilation flags:
`static`
Template:
`shell(Command)`
Mode and number of proofs:
`shell(+atom)` - `zero_or_one`

### `is_absolute_file_name/1`

True iff the argument is an absolute file path.

Compilation flags:
`static`
Template:
`is_absolute_file_name(File)`
Mode and number of proofs:
`is_absolute_file_name(+atom)` - `zero_or_one`

### `absolute_file_name/2`

Expands a file name to an absolute file path. An environment variable at the beginning of the file name is also expanded.

Compilation flags:
`static`
Template:
`absolute_file_name(File,Path)`
Mode and number of proofs:
`absolute_file_name(+atom,-atom)` - `one`

### `decompose_file_name/3`

Decomposes a file name into its directory (which always ends with a slash; `./` is returned if absent) and its basename (which can be the empty atom).

Compilation flags:
`static`
Template:
`decompose_file_name(File,Directory,Basename)`
Mode and number of proofs:
`decompose_file_name(+atom,?atom,?atom)` - `one`

### `decompose_file_name/4`

Decomposes a file name into its directory (which always ends with a slash; `./` is returned if absent), name (that can be the empty atom), and extension (which starts with a `.` when defined; the empty atom otherwise).

Compilation flags:
`static`
Template:
`decompose_file_name(File,Directory,Name,Extension)`
Mode and number of proofs:
`decompose_file_name(+atom,?atom,?atom,?atom)` - `one`

### `path_concat/3`

Concatenates a path prefix and a path suffix, adding a `/` separator if required. Returns `Suffix` when it is an absolute path. Returns `Prefix` with a trailing `/` appended if missing when `Suffix` is the empty atom.

Compilation flags:
`static`
Template:
`path_concat(Prefix,Suffix,Path)`
Mode and number of proofs:
`path_concat(+atom,+atom,--atom)` - `one`

### `make_directory/1`

Makes a new directory. Succeeds if the directory already exists.

Compilation flags:
`static`
Template:
`make_directory(Directory)`
Mode and number of proofs:
`make_directory(+atom)` - `one`

### `make_directory_path/1`

Makes a new directory creating all the intermediate directories if necessary. Succeeds if the directory already exists.

Compilation flags:
`static`
Template:
`make_directory_path(Directory)`
Mode and number of proofs:
`make_directory_path(+atom)` - `one`

### `delete_directory/1`

Deletes an empty directory. Throws an error if the directory does not exist.

Compilation flags:
`static`
Template:
`delete_directory(Directory)`
Mode and number of proofs:
`delete_directory(+atom)` - `one_or_error`

### `change_directory/1`

Changes current working directory. Throws an error if the directory does not exist.

Compilation flags:
`static`
Template:
`change_directory(Directory)`
Mode and number of proofs:
`change_directory(+atom)` - `one_or_error`

### `working_directory/1`

Current working directory.

Compilation flags:
`static`
Template:
`working_directory(Directory)`
Mode and number of proofs:
`working_directory(?atom)` - `zero_or_one`

### `temporary_directory/1`

Temporary directory. Tries first environment variables: `TEMP` and `TMP` on Windows systems; `TMPDIR`, `TMP`, `TEMP`, and `TEMPDIR` on POSIX systems. When not defined, tries default locations. Returns the working directory as last resort.

Compilation flags:
`static`
Template:
`temporary_directory(Directory)`
Mode and number of proofs:
`temporary_directory(?atom)` - `one`

### `null_device_path/1`

Null device path: `nul` on Windows systems and `/dev/null` on POSIX systems.

Compilation flags:
`static`
Template:
`null_device_path(Path)`
Mode and number of proofs:
`null_device_path(?atom)` - `one`

### `directory_files/2`

Returns a list of all files (including directories, regular files, and hidden directories and files) in a directory. File paths are relative to the directory. Throws an error if the directory does not exist.

Compilation flags:
`static`
Template:
`directory_files(Directory,Files)`
Mode and number of proofs:
`directory_files(+atom,-list(atom))` - `one_or_error`

### `directory_files/3`

Returns a list of files filtered using the given list of options. Invalid options are ignored. Default option values are equivalent to `directory_files/2`. Throws an error if the directory does not exist.

Compilation flags:
`static`
Template:
`directory_files(Directory,Files,Options)`
Mode and number of proofs:
`directory_files(+atom,-list(atom),+list(compound))` - `one_or_error`
Remarks:

> - Option `paths/1`: Possible values are `relative` and `absolute`. Default is `relative`.

> - Option `type/1`: Possible values are `all`, `regular`, `directory`. Default is `all`.

> - Option `extensions/1`: Argument is a list of required extensions (using the format `'.ext'`). Default is the empty list.

> - Option `prefixes/1`: Argument is a list of required file prefixes (atoms). Default is the empty list.

> - Option `suffixes/1`: Argument is a list of required file suffixes (atoms). Default is the empty list.

> - Option `dot_files/1`: Possible values are `true` and `false`. Default is `true`.

### `directory_exists/1`

True if the specified directory exists (irrespective of directory permissions).

Compilation flags:
`static`
Template:
`directory_exists(Directory)`
Mode and number of proofs:
`directory_exists(+atom)` - `zero_or_one`

### `ensure_directory/1`

Ensures that a directory exists, creating it if necessary.

Compilation flags:
`static`
Template:
`ensure_directory(Directory)`
Mode and number of proofs:
`ensure_directory(+atom)` - `one`

### `file_exists/1`

True if the specified file exists and is a regular file (irrespective of file permissions).

Compilation flags:
`static`
Template:
`file_exists(File)`
Mode and number of proofs:
`file_exists(+atom)` - `zero_or_one`

### `file_modification_time/2`

File modification time (which can be used for comparison). Throws an error if the file does not exist.

Compilation flags:
`static`
Template:
`file_modification_time(File,Time)`
Mode and number of proofs:
`file_modification_time(+atom,-integer)` - `zero_or_one`

### `file_size/2`

File size (in bytes). Throws an error if the file does not exist.

Compilation flags:
`static`
Template:
`file_size(File,Size)`
Mode and number of proofs:
`file_size(+atom,-integer)` - `zero_or_one`

### `file_permission/2`

True iff the specified file has the specified permission (`read`, `write`, or `execute`). Throws an error if the file does not exist.

Compilation flags:
`static`
Template:
`file_permission(File,Permission)`
Mode and number of proofs:
`file_permission(+atom,+atom)` - `zero_or_one`

### `rename_file/2`

Renames a file or a directory. Throws an error if the file or directory does not exist.

Compilation flags:
`static`
Template:
`rename_file(Old,New)`
Mode and number of proofs:
`rename_file(+atom,+atom)` - `one_or_error`

### `delete_file/1`

Deletes a file. Throws an error if the file does not exist.

Compilation flags:
`static`
Template:
`delete_file(File)`
Mode and number of proofs:
`delete_file(+atom)` - `one_or_error`

### `ensure_file/1`

Ensures that a file exists, creating it if necessary.

Compilation flags:
`static`
Template:
`ensure_file(File)`
Mode and number of proofs:
`ensure_file(+atom)` - `one`

### `environment_variable/2`

Returns an environment variable value. Fails if the variable does not exists.

Compilation flags:
`static`
Template:
`environment_variable(Variable,Value)`
Mode and number of proofs:
`environment_variable(+atom,?atom)` - `zero_or_one`

### `time_stamp/1`

Returns a system-dependent time stamp, which can be used for sorting, but should be regarded otherwise as an opaque term.

Compilation flags:
`static`
Template:
`time_stamp(Time)`
Mode and number of proofs:
`time_stamp(-ground)` - `one`

### `date_time/7`

Returns the current date and time.

Compilation flags:
`static`
Template:
`date_time(Year,Month,Day,Hours,Minutes,Seconds,Milliseconds)`
Mode and number of proofs:
`date_time(-integer,-integer,-integer,-integer,-integer,-integer,-integer)` - `one`

### `cpu_time/1`

System cpu time in seconds.

Compilation flags:
`static`
Template:
`cpu_time(Seconds)`
Mode and number of proofs:
`cpu_time(-number)` - `one`

### `wall_time/1`

Wall time in seconds.

Compilation flags:
`static`
Template:
`wall_time(Seconds)`
Mode and number of proofs:
`wall_time(-number)` - `one`

### `operating_system_type/1`

Operating system type. Possible values are `unix`, `windows`, and `unknown`.

Compilation flags:
`static`
Template:
`operating_system_type(Type)`
Mode and number of proofs:
`operating_system_type(?atom)` - `one`

### `command_line_arguments/1`

Returns a list with the command line arguments that occur after `--`.

Compilation flags:
`static`
Template:
`command_line_arguments(Arguments)`
Mode and number of proofs:
`command_line_arguments(-list(atom))` - `one`

### `sleep/1`

Suspends execution the given number of seconds.

Compilation flags:
`static`
Template:
`sleep(Seconds)`
Mode and number of proofs:
`sleep(+number)` - `one`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)

See also

os, os_types