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

| **Template:**
|    ``internal_os_path(InternalPath,OSPath)``
| **Mode and number of proofs:**
|    ``internal_os_path(+atom,-atom)`` - ``one``
|    ``internal_os_path(-atom,+atom)`` - ``one``


------------

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

