protocol

# `osp`

Portable operating-system access protocol.

Availability:
`logtalk_load(os(loader))`
Author: Paulo Moura
Version: 1:39:0
Date: 2024-10-14
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`

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. On POSIX systems, this predicate is true if `File` starts with a `/`. On Windows systems, this predicate is true if `File` starts with a drive letter. No attempt is made to expand `File` as a 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`

### `internal_os_path/2`

Converts between the internal path representation (which is backend dependent) and the operating-system native path representation.

Compilation flags:
`static`
Template:
`internal_os_path(InternalPath,OSPath)`
Mode and number of proofs:
`internal_os_path(+atom,-atom)` - `one`
`internal_os_path(-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`

### `delete_directory_contents/1`

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

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

### `delete_directory_and_contents/1`

Deletes directory and its contents. Throws an error if the directory does not exist.

Compilation flags:
`static`
Template:
`delete_directory_and_contents(Directory)`
Mode and number of proofs:
`delete_directory_and_contents(+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`

### `full_device_path/1`

Full device path: `/dev/full` on Linux and BSD systems. Fails on other systems. Experimental.

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

### `read_only_device_path/1`

Read-only device path: `/dev/urandom` on macOS. Fails on other systems. Experimental.

Compilation flags:
`static`
Template:
`read_only_device_path(Path)`
Mode and number of proofs:
`read_only_device_path(?atom)` - `zero_or_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)` - `one_or_error`

### `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)` - `one_or_error`

### `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_or_error`

### `copy_file/2`

Copies a file. Throws an error if the original file does not exist or if the copy cannot be created.

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

### `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. Note that most backends do not provide sub-second accuracy and in those cases the value of the `Milliseconds` argument is always zero.

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)` - `zero_or_one`

### `operating_system_name/1`

Operating system name. On POSIX systems, it returns the value of `uname -s`. On Windows systems, it returns `'Windows'`.

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

### `operating_system_machine/1`

Operating system hardware platform. On POSIX systems, it returns the value of `uname -m`. On Windows systems, it returns the value of the `PROCESSOR_ARCHITECTURE` environment variable.

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

### `operating_system_release/1`

Operating system release. On POSIX systems, it returns the value of `uname -r`. On Windows systems, it uses `WMI` code.

Compilation flags:
`static`
Template:
`operating_system_release(Release)`
Mode and number of proofs:
`operating_system_release(?atom)` - `zero_or_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