All Manuals > LispWorks User Guide and Reference Manual > 25 TCP and UDP socket communication and SSL


25.3 Specifying the target for connecting and binding a socket

In general, each socket is bound to a local socket address, and is communicating with some other socket which has its own socket address. The local binding may be done implicitly by the system, but in many cases (in general, when it is a service) it needs to be bound to specific socket address. When connecting to another socket, or sending using UDP socket, the socket address of the other side is needed.

The socket address is always specified by a hostspec and service. hostspec is also referred to as "address" or "hostname" or "host", and the service is sometimes referred to as "port". In particular, the local hostspec and local service are called local-address and local-port.

hostspec specifies an IP address. It can be one of:

A string naming the host, for example "".

Such a string is looked up by the system to find the actual IP address.

A string providing the IP address in standard format.

Example: "" (IPv4)

Example: "2001:500:2f::f" (IPv6).

An integer specifying IPv4 address in network order.

Example: #XCC47B14B.

An ipv6-address object.

The functions string-ip-address and ip-address-string convert between strings that specify addresses and integers or ipv6-address objects. If you need to find the actual address from a string giving the host name, you need to look it up using get-host-entry. Normally you do not need to, because all the interface functions do it implicitly.

service specifies the port number to use. It can be either an integer, which explicitly specifies the port number, or a string, which is either a sequence of decimal digits specifying the port number or a port name that is looked up to find the port number. For example, for http connections the port number is 80. The function get-service-entry can be used to convert between port numbers and names.

When connecting a socket (for example by open-tcp-stream), hostspec and service are required arguments. When binding (for example start-up-server), hostspec (which is normally passed by the keyword argument local-address) can be nil, which means use the local host and allow any connections. service (which is normally passed by the keyword argument local-port) can be specified as 0 or nil, both values meaning that the operating system will select some appropriate port number.

If you have a socket-stream or a socket, you can find what socket address it is bound to by socket-stream-address or get-socket-address, and if it is connected, you can find what address it is connected to by socket-stream-peer-address or get-socket-peer-address.

LispWorks User Guide and Reference Manual - 13 Feb 2015