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

or

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:
Values:
socket-descriptor Open Generic function

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

Signature:

socket-descriptor socket => descriptor

Parameters:
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:
Values:

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:
Values:
remote-host Open Generic function

Returns the remote host for a <socket>.

Signature:

remote-host socket => remote-host-address

Parameters:
Values:

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: init 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>.