### 8.28 Sockets input/output

- Introduction
- socket/2
- socket_close/1
- socket_bind/2
- socket_connect/4
- socket_listen/2
- socket_accept/4, socket_accept/3
- hostname_address/2

#### 8.28.1 Introduction

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 8.10.27) can be used to change this mode. They are also text streams by default. Use set_stream_type/2 (section 8.10.25) to change the type if binary streams are needed.

#### 8.28.2 socket/2

Templates

  socket(+socket_domain, -integer)

Description

socket(Domain, Socket) creates a socket whose domain is Domain (section 8.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 |  | uninstantiation_error(Socket)
an operating system error occurs and the value of the os_error Prolog flag is error (section 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.28.3 socket_close/1

Templates

  socket_close(+integer)

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 8.28.5). In that case simply use close/2 (section 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.28.4 socket_bind/2

Templates

  socket_bind(+integer, +socket_address)

Description

socket_bind(Socket, Address) binds the socket whose descriptor is Socket to the address specified by Address (section 8.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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.28.5 socket_connect/4

Templates

  socket_connect(+integer, +socket_address, -stream, -stream)

Description

socket_connect(Socket, Address, StreamIn, StreamOut) connects the socket whose descriptor is Socket to the address specified by Address (section 8.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 8.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 |  | uninstantiation_error(StreamIn)
StreamOut is not a variable |  | uninstantiation_error(StreamOut)
an operating system error occurs and the value of the os_error Prolog flag is error (section 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.28.6 socket_listen/2

Templates

  socket_listen(+integer, +integer)

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 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicate.

#### 8.28.7 socket_accept/4, socket_accept/3

Templates

  socket_accept(+integer, -atom, -stream, -stream)
  socket_accept(+integer, -stream, -stream)

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 8.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 |  | uninstantiation_error(Client)
StreamIn is not a variable |  | uninstantiation_error(StreamIn)
StreamOut is not a variable |  | uninstantiation_error(StreamOut)
an operating system error occurs and the value of the os_error Prolog flag is error (section 8.22.1) |  | system_error(atom explaining the error)

Portability

GNU Prolog predicates.

#### 8.28.8 hostname_address/2

Templates

  hostname_address(+atom, ?atom)
  hostname_address(?atom, +atom)

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.

Copyright (C) 1999-2021 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright