.. index:: single: osp .. _osp/0: .. rst-class:: right **protocol** ``osp`` ======= Portable operating-system access protocol. | **Availability:** | ``logtalk_load(os(loader))`` | **Author:** Paulo Moura | **Version:** 1:41:0 | **Date:** 2025-05-19 | **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. - CPU and wall time accuracy: Depends on the backend and can be different between CPU and wall time (e.g. CPU time can have nanosecond accuracy with wall time only having millisecond accuracy). | **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:: delete_directory_contents/1 .. _osp/0::delete_directory_contents/1: ``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`` ------------ .. index:: delete_directory_and_contents/1 .. _osp/0::delete_directory_and_contents/1: ``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`` ------------ .. 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. Accuracy depends on the backend. | **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. Accuracy depends on the backend. | **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 macOS systems, it returns ``'Darwin'``. 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 `, :ref:`os_types `