The network Library#

Overview#

The Network library provides internet address protocols and TCP/IP server and client sockets. It exports a single module, called Sockets.

Utilities#

This section covers the start-sockets function, which all libraries using the Network library must call before any other call to the Network library API. It also covers the with-socket-thread macro which registers the current thread as a thread that will call a socket function that blocks.

start-sockets Function#

Signature:

start-sockets () => ()

Discussion:

Applications must call this function before using any other function or variable from the Network library.

This function is necessary because the Win32 API library Winsock2, which the Network library calls to get native socket functionality, requires applications to call an initialization function before calling any Winsock2 API functions. The call to start-sockets calls this underlying Winsock2 function.

Note that you must not call start-sockets from a top-level form in any DLL project. The combination of this, and the restriction that you must call start-sockets before calling anything else, implies that no Network library function or variable can be called (directly or indirectly) from a top-level form in any DLL project. Instead, the DLL project should define a start function that calls start-sockets (directly or indirectly) or re-export start-sockets so that their clients can arrange to have it called from a top-level form in an appropriate EXE project.

Applications using the Network library must arrange for start-sockets to be called (directly or indirectly) before any other sockets API functions. A good place to do this is at the beginning of your startup function (usually called main, or similar). For example:

define method main () => ()
  start-sockets();
  let the-server = make(<tcp-server-socket>, port: 7);
  ...
end;

begin
  main();
end;

New start functions that call start-sockets and that are defined for DLL projects that use the Network library will inherit all of the restrictions described above for start-sockets.

Calling a Network library function before calling start-sockets results in a <sockets-not-initialized> error. Calling start-sockets from a top-level form in a DLL project will result in unpredictable failures — probably access violations during initialization.

with-socket-thread Statement Macro#

Macro Call:

with-socket-thread (#key server?) body end

Discussion:

Registers the current thread as a blocking socket thread, that is, a thread which will call a socket function that blocks, such as read-element or accept.

The reason for the registration is that Network library shutdown can then synchronize with these threads. The early part of the shutdown sequence should cause the threads to unblock with an <end-of-stream-error> so that they can do whatever application cleanup is necessary. Once these threads have exited, the rest of the shutdown sequence can be executed.

A server socket thread (blocking on accept rather than read-element) notices that the shutdown sequence is underway slightly later, with a <blocking-call-interrupted> condition.

Internet addresses#

This section covers Internet address protocols.

Basic Internet address protocol#

This section covers the class <internet-address> and related generic functions and constants.

<internet-address> Open Primary Abstract Instantiable Class#

Superclasses:

<object>

Init-Keywords:

name – An instance of <string> representing a symbolic internet address.
address – An instance of <string> representing a presentation (dotted) form Internet address or an instance of <numeric-address> (see below).

Discussion:

The class of objects representing Internet addresses used as endpoints for peer-to-peer socket connections.

To construct an <internet-address> object you must supply either the name: or address: keyword. For example:

make (<internet-address>, name: "www.whatever.com")

make (<internet-address>, address: "9.74.122.0")

make on <internet-address> returns an instance of <ipv4-address>.

host-name Open Generic function#

Signature:

host-name internet-address => name

Discussion:

Returns an instance of <string> containing a symbolic host name. The internet-address argument must be an instance of <internet-address>.

Usually the name returned is the canonical host name. Note, however, that the implementation is conservative about making DNS calls. Suppose that the <internet-address> instance was created with the name: keyword and no other information. If the application has not made any other requests that would require a DNS call, such as to host-address or aliases, the name that this function returns will be the one specified with the name: keyword, regardless of whether that is the canonical name or not.

host-address Open Generic function#

Signature:

host-address internet-address => address

Discussion:

Returns an instance of <string> containing the presentation form of the host address. In the case of multi-homed hosts this will usually be the same as:

multi-homed-internet-address.all-addresses.first.host-address

In the case of an Internet address created using the address: keyword it will be either the keyword value or all-addresses.first.host-address.

numeric-host-address Open Generic function#

Returns the host address as a <numeric-address>.

Signature:: numeric-host-address internet-address => numeric-address

all-addresses Open Generic function#

Signature:: all-addresses internet-address => sequence
Discussion:: Returns an instance of <sequence> whose elements are <internet-address> objects containing all known addresses for the host.

aliases Open Generic function#

Signature:: aliases internet-address => sequence
Discussion:: Returns an instance of <sequence> whose elements are instances of <string> representing alternative names for the host.

local-host-name Function#

Signature:: local-host-name () => name
Discussion:: Returns an instance of <string> containing a symbolic host name.

The <ipv6-address> class#

This name is reserved for future development.

The <numeric-address> class#

This section describes numeric Internet representation and associated protocols.

<numeric-address> Primary Abstract Sealed Class#

Superclasses:

<object>

Discussion:

The class of objects representing the numeric form of an Internet addresses.

Currently only ipv4 (32-bit) addresses are supported. Ipv6 addresses will be added when they are supported by Winsock2. In general <numeric-address> objects are accessed using the functions host-order or network-order, depending on the context in which they are employed.

network-order Sealed Generic function#

Signature:

network-order address => network-order-address

Discussion:

Returns the value of the numeric address in network order. The argument is a general instance of <numeric-address>. The class of the object returned depends upon the particular subclass of the argument; the network-order method for <ipv4-numeric-address> returns an instance of <machine-word>.

Network order is big-endian byte order.

host-order Sealed Generic function#

Signature:

host-order address => host-order-address

Discussion:

Like network-order but returns the value in host order.

Host order is big-endian byte order on a big-endian host machine and little-endian on a little-endian host machine.

IPV4 addresses#

<ipv4-numeric-address> Open Primary Abstract Instantiable Class#

Superclasses:

<numeric-address>

Init-Keywords:

value – An instance of <machine-word>. Required.
order – One of #"network-order" or #"host-order". Required.

Discussion:

The single slot of this class contains a 32-bit value representing a ipv4 address. This slot is accessed by the generic functions network-order and host-order described above. <ipv4-numeric-address> has two concrete subclasses <ipv4-network-order-address> and <ipv4-host-order-address>. Making a <ipv4-numeric-address> returns one or the other of these depending upon the value of the order: keyword.

host-order(<ipv4-numeric-address>) Method#

Signature:: host-order ipv4-numeric-address => machine-word
Discussion:: Returns the numeric address in host order as an instance of <machine-word>. The argument is an instance of <ipv4-numeric-address>.

network-order(<ipv4-numeric-address>) Method#

Signature:: network-order ipv4-numeric-address => machine-word
Discussion:: Returns the numeric address in network order as an instance of <machine-word>. The argument is an instance of <ipv4-numeric-address>.

as(<string>, <ipv4-numeric-address>) Method#

Returns the presentation (dotted string) form of an instance of <ipv4-numeric-address>.

Signature:: as string ipv4-numeric-address => string

<ipv4-network-order-address> Concrete Sealed Class#

Concrete subclass for network-order numeric addresses.

Superclasses:

<ipv4-numeric-address>

Discussion:

make(<ipv4-network-order-address>)

is equivalent to

make(<ipv4-numeric-address>, order: network-order)

<ipv4-host-order-address> Concrete Sealed Class#

Concrete subclass for host order numeric addresses.

Superclasses:: <ipv4-numeric-address>

Sockets#

This section describes socket classes and protocols.

The <abstract-socket> class#

<abstract-socket> Open Free Abstract Uninstantiable Class#

Superclasses:

<object>

Init-Keywords:

socket-descriptor – A Windows handle or UNIX file descriptor for the socket. In general users of the sockets API should not need to use this keyword. Only implementors of new socket classes should be interested.

Discussion:

The common superclass of all socket objects including <socket> (IP client socket), <server-socket> and <socket-accessor>.

Each subclass of <abstract-socket> must provide methods for close and for the following generic functions:

local-port Open Generic function#

Returns the local port number.

Signature:

local-port socket => port-number

Parameters:

socket – An instance of <socket>, <datagram-socket> or <server-socket>.

Values:

port-number – An instance of <integer>.

socket-descriptor Open Generic function#

Returns the descriptor (handle or fd) for the socket.

Signature:

socket-descriptor socket => descriptor

Parameters:

socket – An instance of <abstract-socket>.

Values:

descriptor – An instance of <accessor-socket-descriptor>.

local-host Open Generic function#

Returns the address of the local host.

Signature:

local-host socket => host-address

Parameters:

socket – An instance of <abstract-socket>.

Values:

host-address – An instance of <internet-address>.

The <server-socket> class#

<server-socket> Open Primary Abstract Instantiable Class#

Superclasses:

<abstract-socket>

Init-Keywords:

service – An instance of <string> containing an abstract name for a service with a “well-known” port, such as "ftp" or "daytime". Valid names depend on the configuration of the DNS. Required unless port: is supplied.
port – An instance of <integer> identifying the port on which the <server-socket> should listen for connection requests. Required unless service: is supplied.
protocol – An instance of <string> naming the protocol. Currently "tcp" is the only supported protocol. You can create instances of protocol-specific subclasses as an alternative to using the protocol: keyword. For example, make(<server-socket>, protocol: "tcp", ...) is equivalent to make(<tcp-server-socket>, ...).

Discussion:

Server-sockets listen on a specified port for connection requests which come in over the network. Either the port: or service: keyword must be supplied.

make on <server-socket> returns an instance of <tcp-server-socket> by default.

accept Open Generic function#

Signature:

accept server-socket #rest args #key => result

Discussion:

Blocks until a connect request is received, then it returns a connected instance of <socket>. The particular subclass of <socket> returned depends on the actual class of the server-socket argument, which must be a general instance of <server-socket>. Calling accept on <tcp-server-socket> returns a connected <tcp-socket>. The keyword arguments are passed to the creation of the <socket> instance.

For UDP sockets accept returns immediately with an instance of <udp-socket>. No blocking happens for UDP sockets because they are connectionless. After reading from a UDP socket returned from accept the socket can be interrogated for the location of the sender using remote-host and remote-port.

with-server-socket Macro#

Macro Call:

with-server-socket (server-var [:: server-class ], keywords)
  body
end

Discussion:

Creates an instance of <server-socket>, using the (optional) server-class argument and keyword arguments to make the <server-socket>, and binds it to the local variable named by server-var. The body is evaluated in the context of the binding and the <server-socket> is closed after the body is executed.

start-server Macro#

Macro Call:

start-server ([server-var = ] socket-server-instance, socket-var [, keywords ])
  body
end

Discussion:

Enters an infinite while(#t) accept loop on the server socket. Each time accept succeeds the <socket> returned from accept is bound to socket-var and body is evaluated in the context of the binding. When body exits, accept is called again producing a new binding for socket-var. The optional keywords are passed to the call to accept.

The <tcp-server-socket> class#

<tcp-server-socket> Class#

Superclasses:

<server-socket>

Init-Keywords:

element-type – Establishes a new default for the element-type of <tcp-socket> instances returned by calling accept on this server socket. This default element-type may be overridden for any particular call to accept by using the element-type: keyword to accept. If no element-type: is specified when the server socket is created, <byte-character> is used as the default element-type.

Discussion:

The class of TCP server sockets. A server socket is an object which listens for requests for connections from the network. When accept is called on the server socket and a request for connection is detected, accept returns a connected <socket>.

accept(<tcp-server-socket>) Method#

Signature:

accept server-socket #rest args #key element-type => connected-socket

Parameters:

server-socket – An instance of <tcp-server-socket>.
element-type (#key) – Controls the element type of the <tcp-socket> (stream) returned. If not supplied, defaults to #f.

Values:

connected-socket – A connected instance of <tcp-socket>.

Discussion:

The other keyword arguments are passed directly to the creation of the <tcp-socket> instance.

The <socket> class#

<socket> Open Free Abstract Instantiable Class#

The class of general client sockets. All client sockets are streams.

Superclasses:

<abstract-socket>, <external-stream>

Init-Keywords:

direction – Specifies the direction of the stream. It must be one of #"input", #"output", and #"input-output". This keyword is an inherited streams class keyword. See The streams Module for a full description.
element-type – An instance of <class>. Useful values are <byte-character> and <byte>. This keyword is an inherited streams class keyword. See The streams Module for a full description.

The <buffered-socket> class#

<buffered-socket> Class#

Superclasses:

<socket>, <double-buffered-stream>

Init-Keywords:

force-output-before-read? – An instance of <boolean>. Defaults to #t. The methods which implement the stream reading protocols (read, read-line, read-element and so on) for instances of <socket> call force-output by default before blocking. This is to ensure that any pending output has been sent to the peer before the socket blocks waiting to read data sent by the peer. This corresponds to the expected, usual behavior of single-threaded client sockets and avoids deadlock in usual cases. Multi-threaded applications, particularly applications where one thread is reading and another thread is writing to the same socket, may wish to inhibit the default force-output. If the socket is created with force-output-before-read?: #f, force-output will not be called before the read functions block.

Discussion:

Socket streams whose elements are bytes or characters. These inherit buffering protocols and the implications of read, write, read-element, write-element, force-output and suchlike methods from <double-buffered-stream>.

The <tcp-socket> class#

The class of TCP client sockets.

<tcp-socket> Class#

The class of TCP client sockets.

Superclasses:

<buffered-socket>

Init-Keywords:

host – An instance of <internet-address> or <string>. The remote host to connect to. The <string> may be either a host name or a presentation-form Internet address. Required.
service – An instance of <string>. A <string> containing an abstract name for a service with a “well-known” port, such as "ftp" or "daytime". Valid names depend on the configuration of the DNS. Required unless port: is supplied.
protocol – An instance of <string> naming the protocol. Currently #"tcp" and #"udp" are the only supported protocols. You can create instances of protocol-specific subclasses as an alternative to using the protocol: keyword. For example make(<socket>, protocol: #"tcp", ...) is equivalent to make(<tcp-socket>, ...). make on <socket> returns an instance of <tcp-socket> by default.
port – An instance of <integer> representing the remote port to connect to. Required unless service: is supplied.
element-type – An instance of <class>. Useful values for <tcp-streams> are <byte-character> and <byte>. This keyword is an inherited streams class keyword. See The streams Module for a full description.

remote-port Open Generic function#

Returns the remote port number for a <socket>.

Signature:

remote-port socket => port-number

Parameters:

socket – An instance of <socket>.

Values:

port-number – An instance of <integer>.

remote-host Open Generic function#

Returns the remote host for a <socket>.

Signature:

remote-host socket => remote-host-address

Parameters:

socket – An instance of <socket>.

Values:

remote-host-address – An instance of <internet-address>.

The <udp-socket> class#

The class of UDP client sockets.

<udp-socket> Class#

The class of UDP client sockets.

Superclasses:

<buffered-socket>

Init-Keywords:

host – An instance of <internet-address> or <string>. The remote host to connect to. The <string> may be either a host name or a presentation-form Internet address. Required.
service – An instance of <string>. A <string> containing an abstract name for a service with a “well-known port”, such as "ftp" or "daytime". Valid names depend on the configuration of the DNS. Required unless port: is supplied.
protocol – An instance of <string> naming the protocol. Currently #"tcp" and #"udp" are the only supported protocols. You can create instances of protocol-specific subclasses as an alternative to using the protocol: keyword. For example make(<socket>, protocol: "udp", ...) is equivalent to make(<UDP-socket>, ...). make on <socket> returns an instance of <tcp-socket> by default.
port – An instance of <integer> representing the remote port to connect to. Required unless service: is supplied.
element-type – An instance of <class>. Useful values for <udp-socket> s are <byte-character> and <byte>. This keyword is an inherited streams class keyword. See The streams Module for a full description.

Discussion:

Of the keywords, host: and one of either service: or port: are required.

The <udp-server-socket> class#

The class of UDP server sockets.

<udp-server-socket> Class#

Superclasses:

<server-socket>

Init-Keywords:

element-type – Establishes a new default for the element-type of <UDP-socket> instances returned by calling accept with this server socket as the argument to accept. This default element-type may be overridden for any particular call to accept by using the element-type: keyword to accept. If no element-type: is specified when the server socket is created, <byte-character> is used as the default element-type.

Discussion:

The class of UDP server sockets. A server socket is an object that listens for requests from the network. When accept is called on the UDP server socket, accept returns a <udp-socket>.

Socket conditions#

This section lists the socket condition classes in the Network library.

<socket-condition> Class#

All socket conditions are general instances of <socket-condition>. Some are recoverable and others are not.

Superclasses:

<simple-condition>

Discussion:

The class of socket conditions. It inherits the format-string: and format-arguments: keywords from <simple-condition>.

Slots:

socket-condition-details

Most socket conditions originate in error return codes from the underlying host operating system’s network library.
The socket-condition-details slot provides information about the low-level failure which was the source for the condition. In most cases this slot will hold an instance of <socket-accessor-condition>.
When creating general instances of <socket-condition>, you can use the details: keyword to set the value for this slot.

<socket-error> Class#

The superclass of all unrecoverable socket conditions.

Superclasses:: <socket-condition>

The class of socket conditions from which no recovery is possible.

<internal-socket-error> Class#

The class of unexpected socket errors.

Superclasses:

<socket-error>

Discussion:

The class of unexpected errors encountered while interacting with the underlying host system’s network library.

Inspect the contents of the socket-condition-details slot for more information.

<recoverable-socket-condition> Class#

The class of socket conditions for which an application may be able to take some remedial action.

Superclasses:

<socket-condition>

Discussion:

The general class of socket conditions for which an application may be able to take some remedial action.

For instance, a web browser receiving such conditions as <connection-refused> or <host-not-found> would normally expect to report those conditions to the user and continue with some other connection request from the user, while a server receiving a <connection-closed> condition from a connected <socket> would probably close the <socket> and continue to handle other requests for connections.

<network-not-responding> Class#

The network — probably a local network — is down. Try again later.

Superclasses:: <recoverable-socket-condition>

<invalid-address> Class#

A badly formed address string has been passed to a function trying to make an <internet-address>.

Superclasses:: <recoverable-socket-condition>

<host-not-found> Class#

The Domain Name Server (DNS) cannot resolve the named host or internet address. Try again with a different (correct) name or address.

Superclasses:: <recoverable-socket-condition>

<server-not-responding> Class#

The Domain Name Server (DNS) did not respond or returned an ambiguous result. Try again.

Superclasses:: <recoverable-socket-condition>

<host-unreachable> Class#

The remote host cannot be reached from this host at this time.

Superclasses:: <recoverable-socket-condition>

<socket-closed> Class#

Superclasses:

<recoverable-socket-condition>

Discussion:

The socket or server socket has been closed.

Most operations on closed instances of <tcp-socket> return instances of <stream-closed-error> (from the Streams library) rather than instances of <socket-closed>.

<connection-failed> Class#

Superclasses:: <recoverable-socket-condition>
Discussion:: The attempt to connect to the remote host was not successful. Connection failed for one of the following reasons: because the connect request timed out or because it was refused, or because the remote host could not be reached.

<connection-closed> Class#

Superclasses:: <recoverable-socket-condition>
Discussion:: The connection to the remote host has been broken. The socket should be closed. To try again, open a new socket.

<address-in-use> Class#

Superclasses:: <recoverable-socket-condition>
Discussion:: A process on the machine is already bound to the same fully qualified address. This condition probably occurred because you were trying to use a port with an active server already installed, or a process crashed without closing a socket.

<blocking-call-interrupted> Class#

A blocking socket call, like read, write or accept, was interrupted.

Superclasses:: <recoverable-socket-condition>

<out-of-resources> Class#

Superclasses:: <recoverable-socket-condition>
Discussion:: The implementation-dependent limit on the number of open sockets has been reached. You must close some sockets before you can open any more.

<socket-accessor-error> Class#

Superclasses:: <socket-error>
Discussion:: An implementation-specific error from the C-FFI interface to the native socket library. Usually instances of this class appear in the socket-condition-details slot of another <socket-condition>.

<win32-socket-error> Class#

Superclasses:

<socket-accessor-error>

Discussion:

A Win32-specific error from the Winsock2 library, a C-FFI interface to the native socket library Winsock2. A function in the FFI library has returned an error return code.

Slots:

WSA-numeric-error-code: Contains the numeric error code that was returned. An instance of <integer>.
WSA-symbolic-error-code: Contains an instance of <string> giving the symbolic (human-readable) form of the error code. For example, the string might be “wsanotsock”.
explanation: An explanation if any of the error. An instance of <string>.
calling-function: The name of Winsock2 FFI interface function which returned the error code. An instance of <string>.