Did you know ... Search Documentation:
Pack logtalk -- logtalk-3.98.0/docs/apis/_sources/socket_0.rst.txt

.. 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:10:0 | Date: 2026-02-11

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