.. index:: osp .. _osp/0:

.. rst-class:: right

protocol

`osp`

Portable operating-system access protocol.

| Availability: | logtalk_load(os(loader))

| Author: Paulo Moura | Version: 1:38:1 | Date: 2024-03-25

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

.. contents:: :local: :backlinks: top

Public predicates

.. index:: pid/1 .. _osp/0::pid/1:

pid/1 ^^^^^^^^^

Returns the process identifier of the running process.

| Compilation flags: | static

| Template: | pid(PID) | Mode and number of proofs: | pid(-integer) - one

.. index:: shell/2 .. _osp/0::shell/2:

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

.. index:: shell/1 .. _osp/0::shell/1:

shell/1 ^^^^^^^^^^^

Runs an operating-system shell command.

| Compilation flags: | static

| Template: | shell(Command) | Mode and number of proofs: | shell(+atom) - zero_or_one

.. index:: is_absolute_file_name/1 .. _osp/0::is_absolute_file_name/1:

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

.. index:: absolute_file_name/2 .. _osp/0::absolute_file_name/2:

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

.. index:: decompose_file_name/3 .. _osp/0::decompose_file_name/3:

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

.. index:: decompose_file_name/4 .. _osp/0::decompose_file_name/4:

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

.. index:: path_concat/3 .. _osp/0::path_concat/3:

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

.. index:: internal_os_path/2 .. _osp/0::internal_os_path/2:

internal_os_path/2 ^^^^^^^^^^^^^^^^^^^^^^

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

| Compilation flags: | static

.. index:: make_directory/1 .. _osp/0::make_directory/1:

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

.. index:: make_directory_path/1 .. _osp/0::make_directory_path/1:

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

.. index:: delete_directory/1 .. _osp/0::delete_directory/1:

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

.. index:: change_directory/1 .. _osp/0::change_directory/1:

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

.. index:: working_directory/1 .. _osp/0::working_directory/1:

working_directory/1 ^^^^^^^^^^^^^^^^^^^^^^^

Current working directory.

| Compilation flags: | static

| Template: | working_directory(Directory) | Mode and number of proofs: | working_directory(?atom) - zero_or_one

.. index:: temporary_directory/1 .. _osp/0::temporary_directory/1:

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

.. index:: null_device_path/1 .. _osp/0::null_device_path/1:

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

.. index:: full_device_path/1 .. _osp/0::full_device_path/1:

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

.. index:: read_only_device_path/1 .. _osp/0::read_only_device_path/1:

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

.. index:: directory_files/2 .. _osp/0::directory_files/2:

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

.. index:: directory_files/3 .. _osp/0::directory_files/3:

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.

.. index:: directory_exists/1 .. _osp/0::directory_exists/1:

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

.. index:: ensure_directory/1 .. _osp/0::ensure_directory/1:

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

.. index:: file_exists/1 .. _osp/0::file_exists/1:

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

.. index:: file_modification_time/2 .. _osp/0::file_modification_time/2:

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

.. index:: file_size/2 .. _osp/0::file_size/2:

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

.. index:: file_permission/2 .. _osp/0::file_permission/2:

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

.. index:: copy_file/2 .. _osp/0::copy_file/2:

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

.. index:: rename_file/2 .. _osp/0::rename_file/2:

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

.. index:: delete_file/1 .. _osp/0::delete_file/1:

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

.. index:: ensure_file/1 .. _osp/0::ensure_file/1:

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

.. index:: environment_variable/2 .. _osp/0::environment_variable/2:

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

.. index:: time_stamp/1 .. _osp/0::time_stamp/1:

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

.. index:: date_time/7 .. _osp/0::date_time/7:

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

.. index:: cpu_time/1 .. _osp/0::cpu_time/1:

cpu_time/1 ^^^^^^^^^^^^^^

System cpu time in seconds.

| Compilation flags: | static

| Template: | cpu_time(Seconds) | Mode and number of proofs: | cpu_time(-number) - one

.. index:: wall_time/1 .. _osp/0::wall_time/1:

wall_time/1 ^^^^^^^^^^^^^^^

Wall time in seconds.

| Compilation flags: | static

| Template: | wall_time(Seconds) | Mode and number of proofs: | wall_time(-number) - one

.. index:: operating_system_type/1 .. _osp/0::operating_system_type/1:

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

.. index:: operating_system_name/1 .. _osp/0::operating_system_name/1:

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

.. index:: operating_system_machine/1 .. _osp/0::operating_system_machine/1:

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

.. index:: operating_system_release/1 .. _osp/0::operating_system_release/1:

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

.. index:: command_line_arguments/1 .. _osp/0::command_line_arguments/1:

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

.. index:: sleep/1 .. _osp/0::sleep/1:

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)

.. seealso::

:ref:`os <os/0>`, :ref:`os_types <os_types/0>`