Attempts to connect to a socket on a server and returns a stream object for the connection.
comm
open-tcp-stream hostspec service &key direction element-type errorp read-timeout write-timeout timeout ssl-ctx ctx-configure-callback ssl-configure-callback handshake-timeout tlsext-host-name local-address ipv6 local-port nodelay keepalive => stream-or-nil, maybe-condition
hostspec⇩ |
An integer or string or an ipv6-address object. |
service⇩ |
A string or a fixnum. |
direction⇩ |
One of :input , :output or :io . |
element-type⇩ | |
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, a foreign pointer or a client ssl-abstract-context. |
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 . | |
handshake-timeout⇩ |
A real or nil (the default). |
tlsext-host-name⇩ |
A string, t or nil . |
local-address⇩ | nil , an integer, a string or a ipv6-address object. |
ipv6⇩ | nil , t or :any . |
local-port⇩ | nil , a string or a fixnum. |
nodelay⇩ |
A generalized boolean. |
keepalive⇩ |
A generalized boolean. |
stream-or-nil⇩ |
A socket-stream or nil . |
maybe-condition⇩ | nil or a condition. |
The function open-tcp-stream
attempts to connect to a socket on a server and returns a socket-stream for the connection if successful.
The IP address to connect to is specified by hostspec, and the service to provide is specified by service. These two arguments are interpreted as described in 25.3 Specifying the target for connecting and binding a socket.
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
(the default), failure to connect (possibly after timeout seconds) returns nil
as stream-or-nil and a condition as maybe-condition. The most common types of condition are socket-connect-error for failure to connect, ssl-failure for failure to attach SSL (maybe because the other side does not use SSL) and ssl-verification-failure for failure during the handshake in a SSL connection. If errorp is non-nil, any failure is signaled by a call to error.
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, ssl-configure-callback and handshake-timeout are interpreted as described in 25.8.6 Keyword arguments for use with SSL. 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 tlsext-host-name is a string, then the SNI extension in the SSL connection to set to its value. If tlsext-host-name is t
and hostspec is a string that does not specify a numeric IP address, then the SNI extension in the SSL connection to set to hostspec. If tlsext-host-name is not supplied and ssl-ctx is non-nil, then the SNI extension is set to hostspec if it is a string that does not specify a numeric IP address and ssl-ctx is not an ssl-abstract-context that was created with a tlsext-host-name.
If local-address is nil
then the operating system chooses the local address of the socket. Otherwise the value is interpreted as for hostspec 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
.
ipv6 specifies the address family to use when hostspec is a string. When ipv6 is :any
, open-tcp-stream
uses either of IPv4 or IPv6. When ipv6 is t
, it uses only IPv6 addresses, and when ipv6 is nil
it tries only IPv4. The default value of ipv6 is :any
.
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
.
/etc/services
. If it is not there, the manual entry for services can be used to find it.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)))
connect-to-tcp-server
start-up-server
socket-stream
socket-stream-shutdown
switch-open-tcp-stream-with-ssl-to-java
open-tcp-stream-using-java
create-ssl-client-context
25 TCP and UDP socket communication and SSL
25 TCP and UDP socket communication and SSL
LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:26