Previous Section | Next Chapter | Table of Contents | Glossary | Index |
make-socket &key
address-family type connect eol format remote-host
remote-port local-host local-port local-filename
remote-filename keepalive reuse-address nodelay broadcast
linger backlog input-timeout output-timeout connect-timeout
auto-close deadline
address-family---The address/protocol family of this socket. Currently only :internet (the default), meaning IP, and :file, referring to UNIX domain addresses, are supported.
type---One of :stream (the default) to request a connection-oriented socket, or :datagram to request a connectionless socket. The default is :stream.
connect---This argument is only relevant to sockets of type :stream. One of :active (the default) to request a :passive to request a file or TCP listener socket.
eol---This argument is currently ignored (it is accepted for compatibility with Franz Allegro).
format---One of :text (the default), :binary, or :bivalent. This argument is ignored for :stream sockets for now, as :stream sockets are currently always bivalent (i.e. they support both character and byte I/O). For :datagram sockets, this argument is ignored (the format of a datagram socket is always :binary).
remote-host---Required for TCP streams, it specifies the host to connect to (in any format acceptable to lookup-hostname). Ignored for listener sockets. For UDP sockets, it can be used to specify a default host for subsequent calls to send-to or receive-from.
remote-port---Required for TCP streams, it specifies the port to connect to (in any format acceptable to lookup-port). Ignored for listener sockets. For UDP sockets, it can be used to specify a default port for subsequent calls to for subsequent calls to send-to or receive-from.
remote-filename---Required for file-socket streams, it specifies the name of a file in the local filesystem (e.g., NOT mounted via NFS, AFP, SMB, ...) which names and controls access to a UNIX-domain socket.
local-host---Allows you to specify a local host address for a listener or UDP socket, for the rare case where you want to restrict connections to those coming to a specific local address for security reasons.
local-port---Specify a local port for a socket. Most useful for listener sockets, where it is the port on which the socket will listen for connections.
local-filename---Required for file-listener-sockets. Specifies the name of a file in the local filesystem which is used to name a UNIX-domain socket. The actual filesystem file should not previously exist when the file-listener-socket is created; its parent directory should exist and be writable by the caller. The file used to name the socket will be deleted when the file-listener-socket is closed.
keepalive---If true, enables the periodic transmission of "keepalive" messages.
reuse-address---If true, allows the reuse of local ports in listener sockets, overriding some TCP/IP protocol specifications. You will need this if you are debugging a server..
nodelay---If true, disables Nagle's algorithm, which tries to minimize TCP packet fragmentation by introducing transmission delays in the absence of replies. Try setting this if you are using a protocol which involves sending a steady stream of data with no replies and are seeing significant degradations in throughput.
broadcast---If true, requests permission to broadcast datagrams on a UDP socket.
linger---If specified and non-nil, should be the number of seconds the OS is allowed to wait for data to be pushed through when a close is done. Only relevant for TCP sockets.
backlog---For a listener socket, specifies the number of connections which can be pending but not accepted. The default is 5, which is also the maximum on some operating systems.
input-timeout---The number of seconds before an input operation
times out. Must be a real number between zero and one
million. If an input operation takes longer than the
specified number of seconds, an
input-timeout
error is signalled.
(see Section 10.1.4, “Stream Timeouts and Deadlines”)
output-timeout---The number of seconds before an output operation
times out. Must be a real number between zero and one
million. If an output operation takes longer than the
specified number of seconds, an
output-timeout
error is signalled.
(see Section 10.1.4, “Stream Timeouts and Deadlines”)
connect-timeout---The number of seconds before a connection
attempt times out. [TODO: what are acceptable values?]
If a connection attempt takes longer than the
specified number of seconds, a
socket-error
is signalled. This
can be useful if the specified interval is shorter
than the interval that the OS's socket layer imposes,
which is sometimes a minute or two.
auto-close---When non-nil, any resulting socket stream will be closed when the GC can prove that the stream is unreferenced. This is done via CCL's termination mechanism [TODO add xref].
deadline---Specifies an absolute time in
internal-time-units. If an I/O operation on the
stream does not complete before the deadline then a
COMMUNICATION-DEADLINE-EXPIRED
error is signalled. A deadline takes precedence over
any input/output timeouts that may be set. (see Section 10.1.4, “Stream Timeouts and Deadlines”)
socket---The listener-socket to listen on.
wait---If true (the default), and there are no connections waiting to be accepted, waits until one arrives. If false, returns NIL immediately.
Extracts the first connection on the queue of pending connections, accepts it (i.e. completes the connection startup protocol) and returns a new tcp-stream or file-socket-stream representing the newly established connection. The tcp stream inherits any properties of the listener socket that are relevant (e.g. :keepalive, :nodelay, etc.) The original listener socket continues to be open listening for more connections, so you can call accept-connection on it again.
socket---The socket to read from
size---Maximum number of bytes to read. If the packet is larger than this, any extra bytes are discarded.
buffer---If specified, must be an octet vector which will be used to read in the data. If not specified, a new buffer will be created (of type determined by socket-format).
extract---If true, the subsequence of the buffer corresponding only to the data read in is extracted and returned as the first value. If false (the default) the original buffer is returned even if it is only partially filled.
offset---Specifies the start offset into the buffer at which data is to be stored. The default is 0.
socket---The socket to write to
buffer---A vector containing the data to send. It must be an octet vector.
size---Number of octets to send
remote-host---The host to send the packet to, in any format acceptable to lookup-hostname. The default is the remote host specified in the call to make-socket.
remote-port---The port to send the packet to, in any format acceptable to lookup-port. The default is the remote port specified in the call to make-socket.
offset---The offset in the buffer where the packet data starts
Returns the native OS's representation of the socket, or NIL if the socket is closed. On Unix, this is the Unix 'file descriptor', a small non-negative integer. Note that it is rather dangerous to mess around with tcp-stream fd's, as there is all sorts of buffering and asynchronous I/O going on above the OS level. listener-socket and udp-socket fd's are safer to mess with directly as there is less magic going on.
A symbol representing the error code in a more OS-independent way.
One of: :address-in-use :connection-aborted :no-buffer-space :connection-timed-out :connection-refused :host-unreachable :host-down :network-down :address-not-available :network-reset :connection-reset :shutdown :access-denied or :unknown.
socket---The socket to close
abort---If false (the default), closes the socket in an orderly fashion, finishing up any buffered pending I/O, before closing the connection. If true, aborts/ignores pending I/O. (For listener and udp sockets, this argument is effectively ignored since there is never any buffered I/O to clean up).
Previous Section | Next Chapter | Table of Contents | Glossary | Index |