Sockets input/output

### 7.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`

#### 7.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 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.

#### 7.28.2 `socket/2`

Templates

  `socket(+socket_domain, -integer)`

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.

#### 7.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 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.

#### 7.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 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.

#### 7.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 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.

#### 7.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 7.22.1) |  | `system_error(atom explaining the error)`

Portability

GNU Prolog predicate.

#### 7.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 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.

#### 7.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-2009 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright