10.21 Socket I/O—library(sockets)

This library package defines a number of predicates for communicating over sockets. To create a (bi-directional) stream connected to a remote server, use socket_client_open/3. To open a port for remote clients to connect to, use socket_server_open/2 and to open a stream to a connecting client, use socket_server_accept/4. To be able to multiplex input and output from several streams (not necesessarily socket streams) and incoming connections, use socket_select/7.

All streams below can be read from as well as written on. All I/O predicates operating on streams can be used, for example get_code/2, get_byte/2, read/2, write/2, format/3, current_stream/3, etc. The predicates that create streams take options similar to open/4, e.g., to specify whether the stream is binary (the default) or text.

socket_client_open(+Addr, -Stream, +Options)

Creates a stream Stream connected to address Addr. Addr can be:

Host:Port

Connect to the machine with address Host (a host name or host address) at port Port (a port number or service name). The Host should be an atom, e.g., 'www.sics.se'. The Port is either a port number as an integer or atom, e.g., 80, or '80'; alternatively some well known port names can be used, e.g., 'http'. The set of well known port names is OS specific, portable code should use integer port numbers.

The stream is created using options from Options. Supported options include:

type(binary)

Create a binary stream (the default).

type(text)

Create a text stream. The default encoding is Latin 1.

eof_action(Action)

end of file action, as for open/4.

To create a binary stream to some web server www.sics.se, you would do e.g.,

          | ?- socket_client_open('www.sics.se':80, Stream, [type(binary)]).
     

or, to make a text (Latin 1) stream to a daytime service in Hong Kong you could do:

          | ?- socket_client_open('stdtime.gov.hk':daytime, S, [type(text)]),
               read_line(S, L),
               format('~s', [L]).
     

See the source code for library('linda/client') for a simple client.

socket_server_open(?Port, -ServerSocket)

Create a server socket ServerSocket that listens on port Port. Port can be either an integer port number or an atomic service name, see socket_client_open/3 for details. Port can also be a variable in which case a free port number is used and Port is bound to it. The created server socket should be closed with socket_server_close/1 eventually. Incoming connection can be accepted with socket_server_accept/4 and waited for with socket_select/7. See the source code for library('linda/server') for a simple server that uses this predicate.

socket_server_accept(+ServerSocket, -Client, -Stream, +StreamOptions)

The first connection to socket ServerSocket is extracted, blocking if necessary. The stream Stream is created on this connection using StreamOptions as for socket_client_open/3. Client will be unified with an atom containing the numerical Internet host address of the connecting client. Note that the stream will be type(binary) unless type(text) is explicitly specified.

socket_server_close(+ServerSocket)

Close the server socket ServerSocket and stop listening on its port.

socket_select(+ServerSockets,-SReady, +ReadStreams,-RReady, +WriteStreams,-WReady, +Timeout)

Check for server sockets with incoming connections (i.e., ready for socket_server_accept/4), streams on ReadStreams ready for input, and streams on WriteStreams ready for output. The streams can be any kind of streams, they need not be socket streams. The ready server sockets are returned (in the same order) in SReady, the ready input streams in RReady, and the ready output streams in WReady.

An input (output) stream is ready for input (output) when an item can be read (written) without blocking. An item is a character for text streams and a byte for binary streams. Note that a stream is considered ready for I/O if the corresponding I/O operation will raise an error (such as if the stream is past end of stream).

Each entry in the input lists ServerSockets, ReadStreams, and WriteStreams can be either a server socket or stream respectively or a term Term-Entry where Entry is the server socket or stream and Term is some arbitrary term used for book-keeping. If an entry is associated with a term in this way then so will the corresponding ready entry.

If TimeOut is instantiated to off, the predicate waits until something is available. If TimeOut is a nonzero number (integer or floating point), then the predicate waits at most that number of seconds before returning. For backward compatibility, if TimeOut is S:U the predicate waits at most S seconds and U microseconds. If there is a timeout, all ready lists are unified with [].

See the source code for library('linda/server') for a simple server that uses this predicate.

current_host(?HostName)

HostName is unified with the fully qualified name of the machine that the process is executing on. The call will also succeed if HostName is instantiated to the unqualified name of the machine in lower case.