Previous Section Next Chapter Table of Contents Glossary Index

Chapter 8. Programming with Sockets

8.2. Sockets Dictionary

[Function]

make-socket &key address-family type connect eol format remote-address remote-host remote-port local-address local-host local-port local-filename remote-filename keepalive reuse-address nodelay broadcast linger backlog input-timeout output-timeout connect-timeout auto-close deadline

Arguments and Values:

address-family---The address/protocol family of this socket. Currently, :internet (the default), meaning IPv4, :internet6, meaning IPv6, 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---For TCP streams, it specifies the socket address to connect to, specified as socket-address instance. Ignored for listener sockets. For UDP sockets, it can be used to specify a default address for subsequent calls to send-to or receive-from.

remote-host---For TCP streams, it specifies the host to connect to (in any format acceptable to resolve-address). 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---For TCP streams, it specifies the port to connect to (in any format acceptable to resolve-address). 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---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-address---Allows you to specify a local address for a listener or UDP socket, for the case where you want to restrict connections to those coming to a specific local address for security reasons.

local-host---Allows you to specify a local host address for a listener or UDP socket, for the 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---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”)

Description:

Creates and returns a new socket. For :passive sockets, the :local-address, :local-port or :local-filename arguments are required, depending on the type of the socket. For :active sockets, either the :remote-address, the :remote-host and :remote-port, or the :remote-filename arguments must be present, depending on the socket type.

[Function]

accept-connection (socket listener-socket) &key wait

Arguments and Values:

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.

Description:

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.

[Function]

resolve-address &key host port socket-type connect address-family numeric-host-p numeric-service-p singlep errorp

Arguments and Values:

host---Specification of the host, as a string. This can be either a host name such as "clozure.com" or any of the literal address forms accepted by getaddrinfo().

port---Specification of the port. This can be either a service name such as "http" or a port number.

socket-type---Service type for port lookups, can be either :stream for TCP services or :datagram for UDP. Defaults to :stream.

connect---Specifies how the returned socket-address instances will be used. If :active is passed, which is the default, the host address will default to the address of the loopback interface of the local host if not specified. When :passive is used, the host address will default to the wildcard address for the given address family. This parameter has no effect if the :host parameter is used.

address-family---Specifies the address family that should be returned, can be specified as either :internet or :internet6. If it is specified, only addresses of that family are returned.

numeric-host-p---If this argument is true, no host name lookups will be performed for the host address. A numeric address literal must be passed in this case.

numeric-port-p---If this argument is true, no service name lookups will be performed for the port address. A numeric port number must be passed in this case.

singlep---If this argument is set to a true value, which is the default, only the first matching address is returned. If it is passed as NIL, all matching addresses are returned as a list.

errorp---If this argument is set to a true value, which is the default, an error is signalled if the given host and/or port combination did not yield any matches. If it is passed as NIL, the function returns NIL if no addresses matched the supplied arguments.

Description:

Converts a host and/or port specification to one or more socket-address instances. This function uses the getaddrinfo() system function underneath which knows how to translate all standard address and port formats and appropriately orders adresses for hosts with multiple addresses. It returns the best matching translation or, if the :singlep argument is passed as false, or all matching translations for the given parameter combination.

[Function]

dotted-to-ipaddr dotted &key errorp

Arguments and Values:

dotted---A string representing an IP address in the "nn.nn.nn.nn" format

errorp---If true (the default) an error is signaled if dotted is invalid. If false, NIL is returned.

Description:

Converts a dotted-string representation of a host address to a 32-bit unsigned IP address.

[Function]

ipaddr-to-dotted ipaddr &key values

Arguments and Values:

ipaddr---A 32-bit integer representing an IPv4 host address

values---If false (the default), returns a string in the form "nn.nn.nn.nn". If true, returns four values representing the four octets of the address as unsigned 8-bit integers.

Description:

Converts a 32-bit unsigned IPv4 address into octets.

[Function]

ipaddr-to-hostname ipaddr &key ignore-cache

Arguments and Values:

ipaddr---a 32-bit integer representing an IPv4 host address

ignore-cache---This argument is ignored (it is accepted for compatibility with Franz Allegro)

Description:

Converts a 32-bit unsigned IPv4 address into a host name string

[Function]

lookup-hostname host

Arguments and Values:

host---Specifies the host. It can be either a host name string such as "clozure.com", or a dotted address string such as "192.168.0.1", or a 32-bit unsigned IPv4 address such as 3232235521.

Description:

Converts a host spec in any of the acceptable formats into a 32-bit unsigned IPv4 address. IPv6-enabled applications should use the resolve-address function instead.

[Function]

lookup-port port protocol

Arguments and Values:

port---Specifies the port. It can be either a string, such as "http" or a symbol, such as :http, or an unsigned port number. Note that a string is case-sensitive. A symbol is lowercased before lookup.

protocol---Must be one of "tcp" or "udp".

Description:

Finds the port number for the specified port and protocol

[Function]

receive-from (socket udp-socket) size &key buffer extract offset

Arguments and Values:

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.

want-socket-address-p---Indicates that the address of the sender of the data should be returned as a socket-address instance rather than as separate host and port values.

Description:

Reads a UDP packet from a socket. If no packets are available, waits for a packet to arrive.

If :want-socket-address-p is NIL, which is the default, four values are returned:

  1. The buffer with the data

  2. The number of bytes read

  3. The 32-bit unsigned IPv4 address or the 16 byte IPv6 addresss of the sender of the data

  4. The port number of the sender of the data

If :want-socket-address-p is true, three values are returned:

  1. The buffer with the data

  2. The number of bytes read

  3. The socket-address instance of the sender of the data.

[Function]

send-to (socket udp-socket) buffer size &key remote remote-host remote-port offset

Arguments and Values:

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---The remote address to send the packet to, as a socket-address instance. The default is the remote address specified in the call to make-socket.

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

Description:

Send a UDP packet over a socket.

[Function]

shutdown socket &key direction

Arguments and Values:

socket---The socket to shut down (typically a tcp-stream)

direction---One of :input to disallow further input, or :output to disallow further output.

Description:

Shuts down part of a bidirectional connection. This is useful if e.g. you need to read responses after sending an end-of-file signal.

[Function]

socket-os-fd socket

Arguments and Values:

socket---The socket

Description:

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.

[Function]

remote-host socket

Arguments and Values:

socket---The socket

Description:

Returns the 32-bit unsigned IPv4 address of the remote host, or NIL if the socket is not connected.

[Function]

remote-port socket

Arguments and Values:

socket---The socket

Description:

Returns the remote port number, or NIL if the socket is not connected.

[Function]

local-host socket

Arguments and Values:

socket---The socket

Description:

Returns 32-bit unsigned IPv4 address or the 16 byte IPv6 address of the local host.

[Function]

local-port socket

Arguments and Values:

socket---The socket

Description:

Returns the local port number

[Function]

socket-address-family thing

Arguments and Values:

thing---The socket or socket-address for which the address family is to be queried.

Description:

Returns :internet, :internet6 or :file, as appropriate.

[Function]

socket-address-host socket-address

Arguments and Values:

socket-address---The socket-address for which the host address is to be queried.

Description:

Returns the host portion of the given socket-address. For :internet addresses, this is a 32-bit integer. For :internet6 addresses, an array of 16 bytes returned. For :file addresses, it is the file name string.

[Function]

socket-address-port socket-address

Arguments and Values:

socket-address---The socket-address for which the port number is to be queried.

Description:

Returns the port number of the given socket-address. This function is available only for :internet and :internet6 socket addresses.

[Function]

socket-connect socket

Arguments and Values:

socket---The socket

Description:

Returns :active for tcp-stream, :passive for listener-socket, and NIL for udp-socket

[Function]

socket-format socket

Arguments and Values:

socket---The socket

Description:

Returns the socket format as specified by the :format argument to make-socket.

[Function]

socket-type socket

Arguments and Values:

socket---The socket

Description:

returns :stream for tcp-stream and listener-socket, and :datagram for udp-socket.

[Class]

SOCKET-ADDRESS

Description:

Representation of a socket endpoint address. Instances of this class are used to encapsulate the host and port of an IP socket endpoint or the filename of a file socket. They can be created by applications from a possibly symbolic address representation by the resolve-address function.

[Class]

SOCKET-ERROR

Description:

The class of OS errors signaled by socket functions

Superclasses:

simple-error

[Function]

socket-error-code socket-error

Arguments and Values:

socket-error---the condition

Description:

The OS error code of the error

[Function]

socket-error-identifier socket-error

Arguments and Values:

socket-error---the condition

Description:

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.

[Function]

socket-error-situation socket-error

Arguments and Values:

socket-error---the condition

Description:

A string describing the context where the error happened. On Linux, this is the name of the system call which returned the error.

[Method]

close (socket socket) &key abort

Arguments and Values:

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).

Description:

The close generic function can be applied to sockets. It releases the operating system resources associated with the socket.

[Macro]

with-open-socket (var . make-socket-args) &body body

Arguments and Values:

var---variable to bind

make-socket-args---arguments suitable for passing to make-socket

body---body to execute

Description:

executes body with var bound to the result of applying make-socket to make-socket-args. The socket gets closed on exit.


Previous Section Next Chapter Table of Contents Glossary Index