This set of predicates provides a way to manipulate sockets. The predicates are straightforward interfaces to the corresponding BSD-type socket functions. This facility is available if the sockets part of GNU Prolog has been installed. A reader familiar with BSD sockets will understand them immediately otherwise a study of sockets is needed.
The domain is either the atom ’AF_INET’ or ’AF_UNIX’ corresponding to the same domains in BSD-type sockets.
An address is either of the form ’AF_INET’(HostName, Port) or ’AF_UNIX’(SocketName). HostName is an atom denoting a machine name, Port is a port number and SocketName is an atom denoting a socket.
By default, streams associated with sockets are block buffered. The predicate set_stream_buffering/2 (section 7.10.27) can be used to change this mode. They are also text streams by default. Use set_stream_type/2 (section 7.10.25) to change the type if binary streams are needed.
Templates
Description
socket(Domain, Socket) creates a socket whose domain is Domain (section 7.28) and unifies Socket with the descriptor identifying the socket. This predicate is an interface to the C Unix function socket(2).
Errors
| Domain is a variable | instantiation_error | |
| Domain is neither a variable nor an atom | type_error(atom, Domain) | |
| Domain is an atom but not a valid socket domain | domain_error(socket_domain, Domain) | |
| Socket is not a variable | type_error(variable, Socket) | |
| an operating system error occurs and the value of the os_error Prolog flag is error (section 7.22.1) | system_error(atom explaining the error) | |
Portability
GNU Prolog predicate.
Templates
Description
socket_close(Socket) closes the socket whose descriptor is Socket. This predicate should not be used if Socket has given rise to a stream, e.g. by socket_connect/4 (section 7.28.5). In that case simply use close/2 (section 7.10.7) on the associated stream.
Errors
| Socket is a variable | instantiation_error | |
| Socket is neither a variable nor an integer | type_error(integer, Socket) | |
| an operating system error occurs and the value of the os_error Prolog flag is error (section 7.22.1) | system_error(atom explaining the error) | |
Portability
GNU Prolog predicate.
Templates
Description
socket_bind(Socket, Address) binds the socket whose descriptor is Socket to the address specified by Address (section 7.28). If Address if of the form ’AF_INET’(HostName, Port) and if HostName is uninstantiated then it is unified with the current machine name. If Port is uninstantiated, it is unified to a port number picked by the operating system. This predicate is an interface to the C Unix function bind(2).
Errors
| Socket is a variable | instantiation_error | |
| Socket is neither a variable nor an integer | type_error(integer, Socket) | |
| Address is a variable | instantiation_error | |
| Address is neither a variable nor a valid address | domain_error(socket_address, Address) | |
| Address = ’AF_UNIX’(E) and E is a variable | instantiation_error | |
| Address = ’AF_UNIX’(E) or ’AF_INET’(E, _) and E is neither a variable nor an atom | type_error(atom, E) | |
| Address = ’AF_UNIX’(E) and E is an atom but not a valid pathname | domain_error(os_path, E) | |
| Address = ’AF_INET’(_, E) and E is neither a variable nor an integer | type_error(integer, E) | |
| an operating system error occurs and the value of the os_error Prolog flag is error (section 7.22.1) | system_error(atom explaining the error) | |
Portability
GNU Prolog predicate.
Templates
Description
socket_connect(Socket, Address, StreamIn, StreamOut) connects the socket whose descriptor is Socket to the address specified by Address (section 7.28). StreamIn is unified with a stream-term associated with the input of the connection (it is an input stream). Reading from this stream gets data from the socket. StreamOut is unified with a stream-term associated with the output of the connection (it is an output stream). Writing to this stream sends data to the socket. The use of select/5 can be useful (section 7.27.29). This predicate is an interface to the C Unix function connect(2).
Errors
| Socket is a variable | instantiation_error | |
| Socket is neither a variable nor an integer | type_error(integer, Socket) | |
| Address is a variable | instantiation_error | |
| Address is neither a variable nor a valid address | domain_error(socket_address, Address) | |
| Address = ’AF_UNIX’(E) or ’AF_INET’(E, _) or Address = ’AF_INET’(_, E) and E is a variable | instantiation_error | |
| Address = ’AF_UNIX’(E) or ’AF_INET’(E, _) and E is neither a variable nor an atom | type_error(atom, E) | |
| Address = ’AF_UNIX’(E) and E is an atom but not a valid pathname | domain_error(os_path, E) | |
| Address = ’AF_INET’(_, E) and E is neither a variable nor an integer | type_error(integer, E) | |
| StreamIn is not a variable | type_error(variable, StreamIn) | |
| StreamOut is not a variable | type_error(variable, StreamOut) | |
| an operating system error occurs and the value of the os_error Prolog flag is error (section 7.22.1) | system_error(atom explaining the error) | |
Portability
GNU Prolog predicate.
Templates
Description
socket_listen(Socket, Length) defines the socket whose descriptor is Socket to have a maximum backlog queue of Length pending connections. This predicate is an interface to the C Unix function listen(2).
Errors
| Socket is a variable | instantiation_error | |
| Socket is neither a variable nor an integer | type_error(integer, Socket) | |
| Length is a variable | instantiation_error | |
| Length is neither a variable nor an integer | type_error(integer, Length) | |
| an operating system error occurs and the value of the os_error Prolog flag is error (section 7.22.1) | system_error(atom explaining the error) | |
Portability
GNU Prolog predicate.
Templates
Description
socket_accept(Socket, Client, StreamIn, StreamOut) extracts the first connection to the socket whose descriptor is Socket. If the domain is ’AF_INET’, Client is unified with an atom whose name is the Internet host address in numbers-and-dots notation of the connecting machine. StreamIn is unified with a stream-term associated with the input of the connection (it is an input stream). Reading from this stream gets data from the socket. StreamOut is unified with a stream-term associated with the output of the connection (it is an output stream). Writing to this stream sends data to the socket. The use of select/5 can be useful (section 7.27.29). This predicate is an interface to the C Unix function accept(2).
socket_accept(Socket, StreamIn, StreamOut) is equivalent to
socket_accept(Socket, _,
StreamIn, StreamOut).
Errors
| Socket is a variable | instantiation_error | |
| Socket is neither a variable nor an integer | type_error(integer, Socket) | |
| Client is not a variable | type_error(variable, Client) | |
| StreamIn is not a variable | type_error(variable, StreamIn) | |
| StreamOut is not a variable | type_error(variable, StreamOut) | |
| an operating system error occurs and the value of the os_error Prolog flag is error (section 7.22.1) | system_error(atom explaining the error) | |
Portability
GNU Prolog predicates.
Templates
Description
hostname_address(HostName, HostAddress) succeeds if the Internet host address in numbers-and-dots notation of HostName is HostAddress. Hostname can be given as a fully qualified name, or an unqualified name or an alias of the machine. The predicate will fail if the machine name or address cannot be resolved.
Errors
| HostName and HostAddress are variables | instantiation_error | |
| HostName is neither a variable nor an atom | type_error(atom, HostName) | |
| HostAddress is neither a variable nor an atom | type_error(atom, HostAddress) | |
| Address is neither a variable nor a valid address | domain_error(socket_address, Address) | |
Portability
GNU Prolog predicate.