Socket I/O

This library package defines a number of predicates manipulating sockets. They are all rather straight-forward interfaces to the corresponding BSD-type socket functions with the same name (except current_host/1). The reader should therefore study the appropriate documents for a deeper description.

The Domain is either the atom 'AF_INET' or 'AF_UNIX'. They correspond directly to the same domains in BSD-type sockets. 'AF_UNIX' may not be available on non-UNIX platforms.

An Address is either 'AF_INET'(Host,Port) or 'AF_UNIX'(SocketName). Host is an atomic hostname, Port is a portnumber and SocketName is an atom denoting a socket. A reader familiar with BSD sockets will understand this immediately.

All streams below can be both read from and written on. All I/O-predicates operating on streams can be used, for example read/2, write/2, format/3, current_stream/3, etc. Socket streams are unbuffered on reads and block buffered on writes.

To load the package, enter the query

| ?- use_module(library(sockets)).

socket(+Domain, -Socket)

A socket Socket in the domain Domain is created.

socket_close(+Socket)

Socket is closed. Sockets used in socket_connect/2 should not be closed by socket_close/1 as they will be closed when the corresponding stream is closed.

socket_bind(+Socket, 'AF_UNIX'(+SocketName))

socket_bind(+Socket, 'AF_INET'(?Host,?Port))

The socket Socket is bound to the address. If Port is uninstantiated, the operative system picks a port number to which Port is bound.

socket_connect(+Socket, 'AF_UNIX'(+SocketName), -Stream)

socket_connect(+Socket, 'AF_INET'(+Host,+Port), -Stream)

The socket Socket is connected to the address. Stream is a special stream on which items can be both read and written.

socket_listen(+Socket, +Length)

The socket Socket is defined to have a maximum backlog queue of Length pending connections.

socket_accept(+Socket, -Stream)

socket_accept(+Socket, -Client, -Stream)

The first connection to socket Socket is extracted. The stream Stream is opened for read and write on this connection. For the 'AF_INET' domain, Client will unified with an atom containing the Internet host address of the connecting entity in numbers-and-dots notation. For other domains, Client will not be used.

socket_select(+TermsSockets, -NewTermsStreams, +TimeOut, +Streams, -ReadStreams)

The list of streams in Streams is checked for readable characters. A stream can be any stream associated with an I/O descriptor. The list ReadStreams returns the streams with readable data. socket_select/5 also waits for connections to the sockets specified by TermsSockets. This argument should be a list of Term-Socket pairs, where Term, which can be any term, is used as an identifier. NewTermsStreams is a list of Term-connection(Client,Stream) pairs, where Stream is a new stream open for communicating with a process connecting to the socket identified with Term, Client is the client host address (see socket_accept/3). If TimeOut is instantiated to off, the predicate waits until something is available. If TimeOut is S:U the predicate waits at most S seconds and U microseconds. Both S and U must be integers >=0. If there is a timeout, ReadStreams and NewTermsStreams are [].

socket_select(+Sockets, -NewStreams, +TimeOut, +Streams, -ReadStreams)

socket_select(+Socket, -NewStream, +TimeOut, +Streams, -ReadStreams)

socket_select(+Sockets, -NewStreams, -NewClients, +TimeOut, +Streams, -ReadStreams)

socket_select(+Socket, -NewStream, -NewClient, +TimeOut, +Streams, -ReadStreams)

These forms, which are provided for backward compatibility only, differs in how sockets are specified and new streams returned. socket_select/5-6 also wait for connections to the sockets in the list Sockets. NewStreams is the list of new streams opened for communicating with the connecting processes. NewClients is the corresponding list of client host addresses (see socket_accept/3). The second form requires one socket (not a list) for the first argument and returns a stream, NewStream, if a connection is made.

current_host(?HostName)

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

hostname_address(+HostName, -HostAddress)

hostname_address(-HostName, +HostAddress)

The Internet host is resolved given either the host name or address. HostAddress should be an atom containing the Internet host address in numbers-and-dots notation. The predicate will fail if the host name or address cannot be resolved.