Function

Summary

Attempts to connect to a socket on a server.

Package

comm

Signature

connect-to-tcp-server host service &key errorp timeout local-address local-port keepalive nodelay => handle

Arguments

host

An integer or string or an ipv6-address object.

service

A string or a fixnum.

errorp

A boolean.

timeout

A positive number, or nil .

local-address

nil , an integer, a string or an ipv6-address object.

local-port

nil , a string or a fixnum.

nodelay

A generalized boolean.

keepalive

A generalized boolean.

Values

handle

A handle suitable for a socket-stream or a subclass.

Description

The function connect-to-tcp-server attempts to connect to a socket on a server and returns a handle for the connection if successful. This handle can then be used as the socket when making a socket-stream.

The server machine to connect to is given by hostname , which can be one of the following:

• A string naming the host, for example "www.nowhere.com"
• A string providing the IP address, for example "204.71.177.75" or "2001:500:2f::f"
• An integer IP address in network order, for example #xCC47B14B
• An ipv6-address object.

The name of the service to provide is given by service . If service is a string, the location of the file specifying the names of the services available varies, but typically on Windows 98 it is called SERVICES and is stored in the Windows directory., and on Windows NT-based systems it is the file

%SystemRoot%\system32\drivers\etc\SERVICES

The service can also be a fixnum representing the port number of the desired connection.

If errorp is nil , failure to connect (possibly after timeout seconds) returns nil , otherwise an error is signaled.

timeout specifies a connection timeout. connect-to-tcp-server waits for at most timeout seconds for the TCP connection to be made. If timeout is nil it waits until the connection attempt succeeds or fails. On failure, connect-to-tcp-server signals an error or returns nil according to the value of errorp . To provide a timeout for reads after the connection is made, see read-timeout in socket-stream. The default value of timeout is nil .

If local-address is nil then the operating system chooses the local address of the socket. Otherwise the value is interpreted as for hostname and specifies the local address of the socket. The default value of local-address is nil .

If local-port is nil then the operating system chooses the local port of the socket. Otherwise the string or fixnum value is interpreted as for service and specifies the local port of the socket. The default value of local-port is nil .

If keepalive is true, SO_KEEPALIVE is set on the socket. The default value of keepalive is nil .

If nodelay is true, TCP_NODELAY is set on the socket. The default value of nodelay is t .

Notes

1. On Unix the name of the service can normally be found in / etc/services . If it is not there, the manual entry for services can be used to find it.
2. In most situations, open-tcp-stream, which returns a stream rather than a handle, is the more convenient interface. connect-to-tcp-server is useful when want to associate further information with the stream. You can define a subclass of socket-stream, connect using connect-to-tcp-server , and call make-instance with your subclass, passing the handle as the socket.

See also

socket-stream
open-tcp-stream