Function

Summary

Attempts to connect to a socket on a server and returns a stream object for the connection.

Package

comm

Signature

open-tcp-stream hostname service &key direction element-type errorp read-timeout write-timeout timeout ssl-ctx ctx-configure-callback ssl-configure-callback local-address local-port nodelay keepalive => stream-object

Arguments

hostname

An integer or string or an ipv6-address object.

service

A string or a fixnum.

direction

One of :input , :output or :io .

element-type

base-char or a subtype of integer .

errorp

A boolean.

read-timeout

A positive number, or nil .

write-timeout

A positive number, or nil .

timeout

A positive number, or nil .

ssl-ctx

A symbol or a foreign pointer.

ctx-configure-callback

A function designator or nil . The default value is nil .

ssl-configure-callback

A function designator or nil . The default value is nil .

local-address

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

local-port

nil , a string or a fixnum.

nodelay

A generalized boolean.

keepalive

A generalized boolean.

Values

stream-object

A socket stream.

Description

The function open-tcp-stream attempts to connect to a socket on a server and returns stream-object for the connection if successful. 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.

The direction of the connection is given by direction . Its default value is :io . The element type of the connection is determined from element-type , and is base-char by default.

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

timeout specifies a connection timeout. open-tcp-stream 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, open-tcp-stream 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 . The default value of timeout is nil .

read-timeout specifies the read timeout of the stream. If it is nil (the default), the stream does not time out during reads, and these may hang. See socket-stream for more details. To provide a connection timeout, see timeout .

write-timeout is similar to read-timeout , but for writes. See socket-stream for more details.

ssl-ctx , ctx-configure-callback and ssl-configure-callback are interpreted as described for socket-stream. Unlike the other ways of creating a socket stream with SSL processing, open-tcp-stream does not take the ssl-side argument and always uses the value :client .

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

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.

Example

The following example opens an HTTP connection to a given host, and retrieves the root page:

(with-open-stream (http (comm:open-tcp-stream 

                         "www.lispworks.com" 80))

  (format http "GET / HTTP/1.0~C~C~C~C"

               (code-char 13) (code-char 10)

               (code-char 13) (code-char 10))

  (force-output http)

  (write-string "Waiting to reply...")

  (loop for ch = (read-char-no-hang http nil :eof)

        until ch

        do (write-char #\.)

           (sleep 0.25)

        finally (unless (eq ch :eof)

                  (unread-char ch http))) 

  (terpri)

  (loop for line = (read-line http nil nil)

        while line

        do (write-line line)))

See also

connect-to-tcp-server
start-up-server
socket-stream