Next: lib-statistics, Previous: lib-sets, Up: The Prolog Library [Contents][Index]
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,3]
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
necessarily socket streams) and incoming connections, use
socket_select/7
.
When opening a client or server socket a socket address needs to be specified. The address specifies the address family and family-specific information. The following formats are supported for socket addresses:
inet(Nodename,Servname)
Nodename:Servname
Servname
This specifies the address for and ordinary internet
socket (AF_INET
or AF_INET6
).
Nodename is the internet address of the remote host, as an
atom, something like 'sicstus.sics.se'
or
'193.10.64.51'
. The empty nodename ''
(the default),
has special meaning, see the documentation for
socket_client_open/3
and socket_server_open/[2,3]
.
Servname is either a port number as an atom of decimal
digits or as an integer, 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.
Servname can also be a variable when opening a server socket
with socket_server_open/[2,3]
. In this case a available
port is assigned automatically and Servname is bound to it.
unix(Path) since release 4.0.3
A Unix domain (AF_UNIX
) socket is opened at the specified
file system location. This is only supported on Unix-like
platforms.
Path is a file-name and is passed to
absolute_file_name/2
. There may be platform-specific
restrictions on the length of the resulting pathname and the file
system containing it.
All streams below can be read from as well as written to. 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.
See above for the allowed address formats. If the nodename is
empty (''
) then a connection is made to the local machine.
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
.
encoding(ENCODING) since release 4.1
As for open/4. Implies type(text)
.
eol(Eol) since release 4.1
As for open/4. Implies type(text)
.
To create a binary stream to some web server sicstus.sics.se
, you
would do e.g.
| ?- use_module(library(sockets)). % only needed once per SICStus session. … | ?- socket_client_open('sicstus.sics.se':80, Stream, [type(binary)]).
or, to make a text (Latin 1)
stream to a daytime
service in Hong Kong you could do:
| ?- use_module(library(sockets)). % only needed once per SICStus session. … | ?- 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(?Addr, -ServerSocket, +Options) since release 4.0.3
Create a server socket ServerSocket that listens on address Addr.
See above for the allowed address formats. If the nodename is
empty (''
) then any remote client machine is allowed to
connect unless the option loopback(true)
is also specified.
Addr
can specify an internet address where the port is a variable in
which case a free port number is used and Port is bound to
it. The common case is that Addr is a numeric port number or a
variable that becomes bound to a free port number.
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.
Options is a list of options, currently
reuseaddr(Bool) since release 4.0.3
Bool is either true
or false
(the default). If
true
then allow reuse of local addresses. For internet
sockets this corresponds to the SO_REUSEADDR
socket
option. For unix domain sockets this means that the file will be
deleted, if present, before opening.
numeric_nodename(Bool) since release 4.0.3
Bool is either true
or false
(the default). If
true
then the nodename of an internet address will be
treated as a numerical address and no name lookup will be
performed.
numeric_servname(Bool) since release 4.0.3
Bool is either true
or false
(the default). If
true
then the servname of an internet address will be
treated as a numerical port number and no lookup of well
known port names will be performed.
loopback(Bool) since release 4.0.3
Bool is either true
or false
(the default). If
true
then the nodename will be ignored and the socket will
only listen to connection from the loopback device, i.e. the
local machine.
socket_server_open(?Port, -ServerSocket)
The same as
socket_server_open(Port, ServerSocket, [])
.
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 specified either explicitly or implicitly
with encoding/1
or other text-only options.
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. Please note: this predicate will fail if there are errors, e.g. if no domain has been configured.