Sockets input/output

6.28 | Sockets input/output

6.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 to sockets are `block` buffered. The predicate `set_stream_buffering/2` (section 6.10.24) can be used to change this mode. They are also text streams by default. Use `set_stream_type/2` (section 6.10.22) to change the type if binary streams are needed.

6.28.2 | `socket/2`

Templates

  `socket(+socket_domain, -integer)`

Description
`socket(Domain, Socket)` creates a socket whose domain is `Domain` (section 6.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 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

6.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/2` (section 6.28.5). In that case simply use `close/2` (section 6.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 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

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

Portability
GNU Prolog predicate.

6.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 6.28). `StreamIn` is unified with a stream-term associated to 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 to 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 6.27.27). 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 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicate.

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

Portability
GNU Prolog predicate.

6.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 to 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 to 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 6.27.27). 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 6.22.1) |  | `system_error(``atom explaining the error``)`

Portability
GNU Prolog predicates.

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