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

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

osp

`osp`