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

.. rst-class:: right

**protocol**

``osp``
=======

Portable operating-system access protocol.

| **Author:** Paulo Moura
| **Version:** 1:32:0
| **Date:** 2021-11-30

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

.. raw:: html

   <div id="pid/1"> </div>

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


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

.. raw:: html

   <div id="shell/2"> </div>

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


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

.. raw:: html

   <div id="shell/1"> </div>

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


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

.. raw:: html

   <div id="is_absolute_file_name/1"> </div>

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

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``is_absolute_file_name(File)``
| **Mode and number of proofs:**
|    ``is_absolute_file_name(+atom)`` - ``zero_or_one``


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

.. raw:: html

   <div id="absolute_file_name/2"> </div>

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


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

.. raw:: html

   <div id="decompose_file_name/3"> </div>

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


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

.. raw:: html

   <div id="decompose_file_name/4"> </div>

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


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

.. raw:: html

   <div id="path_concat/3"> </div>

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


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

.. raw:: html

   <div id="internal_os_path/2"> </div>

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


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

.. raw:: html

   <div id="make_directory/1"> </div>

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


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

.. raw:: html

   <div id="make_directory_path/1"> </div>

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


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

.. raw:: html

   <div id="delete_directory/1"> </div>

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


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

.. raw:: html

   <div id="change_directory/1"> </div>

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


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

.. raw:: html

   <div id="working_directory/1"> </div>

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


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

.. raw:: html

   <div id="temporary_directory/1"> </div>

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


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

.. raw:: html

   <div id="null_device_path/1"> </div>

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


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

.. raw:: html

   <div id="directory_files/2"> </div>

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


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

.. raw:: html

   <div id="directory_files/3"> </div>

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


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

.. raw:: html

   <div id="directory_exists/1"> </div>

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


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

.. raw:: html

   <div id="ensure_directory/1"> </div>

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


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

.. raw:: html

   <div id="file_exists/1"> </div>

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


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

.. raw:: html

   <div id="file_modification_time/2"> </div>

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


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

.. raw:: html

   <div id="file_size/2"> </div>

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


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

.. raw:: html

   <div id="file_permission/2"> </div>

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


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

.. raw:: html

   <div id="copy_file/2"> </div>

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


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

.. raw:: html

   <div id="rename_file/2"> </div>

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


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

.. raw:: html

   <div id="delete_file/1"> </div>

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


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

.. raw:: html

   <div id="ensure_file/1"> </div>

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


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

.. raw:: html

   <div id="environment_variable/2"> </div>

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


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

.. raw:: html

   <div id="time_stamp/1"> </div>

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


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

.. raw:: html

   <div id="date_time/7"> </div>

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

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


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

.. raw:: html

   <div id="cpu_time/1"> </div>

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


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

.. raw:: html

   <div id="wall_time/1"> </div>

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


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

.. raw:: html

   <div id="operating_system_type/1"> </div>

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


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

.. raw:: html

   <div id="command_line_arguments/1"> </div>

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


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

.. raw:: html

   <div id="sleep/1"> </div>

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

