.. index:: single: socket
.. _socket/0:

.. rst-class:: right

**object**

``socket``
==========

Portable abstraction over TCP sockets. Provides a high-level API for client and server socket operations that works with selected backend Prolog systems.

| **Availability:** 
|    ``logtalk_load(sockets(loader))``

| **Author:** Paulo Moura
| **Version:** 0:13:0
| **Date:** 2026-04-22

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Imports:**
|    ``public`` :ref:`options <options/0>`
| **Uses:**
|    :ref:`list <list/0>`

| **Remarks:**

   - Supported backends: ECLiPSe, GNU Prolog, SICStus Prolog, SWI-Prolog, and Trealla Prolog.
   - Design rationale: Some backends (notably SICStus Prolog) do not provide low-level socket creation predicates that can be separated from binding or connecting. This library therefore provides a higher-level API with ``client_open/5`` and ``server_open/3`` that abstracts over these differences.
   - Stream handling: Predicates ``client_open/5`` and ``server_accept/5`` return separate input and output streams opened in binary mode. For backends where the same stream is used for bidirectional communication, the same stream handle is returned in both arguments. Use standard stream predicates (``put_byte/2``, ``get_byte/2``, ``read/2``, ``write/2``, etc.) to communicate.
   - Options: Currently options are only defined for the ``server_open/3`` predicate. This is expected to change in future versions for the other predicates that have an options argument.

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

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

Public predicates
-----------------

.. index:: client_open/5
.. _socket/0::client_open/5:

``client_open/5``
^^^^^^^^^^^^^^^^^

Opens a client connection to the specified host and port using the given options. Returns separate input and output streams for bidirectional communication. The streams are opened by default in binary mode.

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

| **Template:**
|    ``client_open(Host,Port,InputStream,OutputStream,Options)``
| **Mode and number of proofs:**
|    ``client_open(+atom,+integer,--stream,--stream,+list)`` - ``one_or_error``

| **Exceptions:**
|    Connection refused or host not found:
|        ``socket_error(Error)``

| **Remarks:**

    - Option ``type(binary)``: Open the streams in binary mode. This is the default.
    - Option ``type(text)``: Open the streams in text mode.


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

.. index:: client_open/4
.. _socket/0::client_open/4:

``client_open/4``
^^^^^^^^^^^^^^^^^

Opens a client connection to the specified host and port using default options. Returns separate input and output streams for bidirectional communication. The streams are opened in binary mode.

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

| **Template:**
|    ``client_open(Host,Port,InputStream,OutputStream)``
| **Mode and number of proofs:**
|    ``client_open(+atom,+integer,--stream,--stream)`` - ``one_or_error``

| **Exceptions:**
|    Connection refused or host not found:
|        ``socket_error(Error)``


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

.. index:: server_open/4
.. _socket/0::server_open/4:

``server_open/4``
^^^^^^^^^^^^^^^^^

Opens a server socket bound to the specified host and port using the given options. If ``Port`` is a variable, binds to an available port and unifies ``Port`` with the port number. Returns a ``ServerSocket`` handle to use with ``server_accept/4``. The default backlog (queue length) for pending connections is 5. Use the option ``backlog(N)`` to override. This option is not supported and thus ignored by the SICStus Prolog and Trealla Prolog backends.

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

| **Template:**
|    ``server_open(Host,Port,ServerSocket,Options)``
| **Mode and number of proofs:**
|    ``server_open(+atom,?integer,--compound,+list)`` - ``one_or_error``

| **Exceptions:**
|    Port already in use:
|        ``socket_error(Error)``


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

.. index:: server_open/3
.. _socket/0::server_open/3:

``server_open/3``
^^^^^^^^^^^^^^^^^

Opens a server socket bound to the specified port using the given options. If ``Port`` is a variable, binds to an available port and unifies ``Port`` with the port number. Returns a ``ServerSocket`` handle to use with ``server_accept/4``. The default backlog (queue length) for pending connections is 5. Use the option ``backlog(N)`` to override. This option is not supported and thus ignored by the SICStus Prolog and Trealla Prolog backends.

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

| **Template:**
|    ``server_open(Port,ServerSocket,Options)``
| **Mode and number of proofs:**
|    ``server_open(?integer,--compound,+list)`` - ``one_or_error``

| **Exceptions:**
|    Port already in use:
|        ``socket_error(Error)``


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

.. index:: server_open/2
.. _socket/0::server_open/2:

``server_open/2``
^^^^^^^^^^^^^^^^^

Opens a server socket bound to the specified port using default options. If ``Port`` is a variable, binds to an available port and unifies ``Port`` with the port number. Returns a ``ServerSocket`` handle to use with ``server_accept/4``. The default backlog (queue length) for pending connections is 5.

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

| **Template:**
|    ``server_open(Port,ServerSocket)``
| **Mode and number of proofs:**
|    ``server_open(?integer,--compound)`` - ``one_or_error``

| **Exceptions:**
|    Port already in use:
|        ``socket_error(Error)``


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

.. index:: server_accept/5
.. _socket/0::server_accept/5:

``server_accept/5``
^^^^^^^^^^^^^^^^^^^

Accepts an incoming connection on the server socket, blocking until a client connects, using the given options. Returns separate input and output streams for bidirectional communication and client information as ``client(Host, Port)`` or ``client(Address)`` depending on backend. The streams are opened by default in binary mode.

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

| **Template:**
|    ``server_accept(ServerSocket,InputStream,OutputStream,ClientInfo,Options)``
| **Mode and number of proofs:**
|    ``server_accept(+compound,--stream,--stream,--compound,+list)`` - ``one_or_error``

| **Exceptions:**
|    Invalid server socket:
|        ``socket_error(Error)``

| **Remarks:**

    - Option ``type(binary)``: Open the streams in binary mode. This is the default.
    - Option ``type(text)``: Open the streams in text mode.


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

.. index:: server_accept/4
.. _socket/0::server_accept/4:

``server_accept/4``
^^^^^^^^^^^^^^^^^^^

Accepts an incoming connection on the server socket, blocking until a client connects, using default options. Returns separate input and output streams for bidirectional communication and client information as ``client(Host, Port)`` or ``client(Address)`` depending on backend. The streams are opened in binary mode.

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

| **Template:**
|    ``server_accept(ServerSocket,InputStream,OutputStream,ClientInfo)``
| **Mode and number of proofs:**
|    ``server_accept(+compound,--stream,--stream,--compound)`` - ``one_or_error``

| **Exceptions:**
|    Invalid server socket:
|        ``socket_error(Error)``


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

.. index:: server_close/1
.. _socket/0::server_close/1:

``server_close/1``
^^^^^^^^^^^^^^^^^^

Closes a server socket.

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

| **Template:**
|    ``server_close(ServerSocket)``
| **Mode and number of proofs:**
|    ``server_close(+compound)`` - ``one_or_error``


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

.. index:: close/2
.. _socket/0::close/2:

``close/2``
^^^^^^^^^^^

Closes a client or accepted connection by closing both the input and output streams. If the same stream is used for both, it is closed only once.

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

| **Template:**
|    ``close(InputStream,OutputStream)``
| **Mode and number of proofs:**
|    ``close(+stream,+stream)`` - ``one_or_error``


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

.. index:: current_host/1
.. _socket/0::current_host/1:

``current_host/1``
^^^^^^^^^^^^^^^^^^

Returns the hostname of the current machine.

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

| **Template:**
|    ``current_host(Host)``
| **Mode and number of proofs:**
|    ``current_host(-atom)`` - ``one_or_error``


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

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

