CHICKEN User's Manual - Unit tcp

# Unit tcp

This unit provides basic facilities for communicating over TCP sockets. The socket interface should be mostly compatible to the one found in PLT Scheme.

This unit uses the `extras` unit.

All errors related to failing network operations will raise a condition of kind `(exn i/o network)`.

## tcp-listen

    [procedure] (tcp-listen TCPPORT [BACKLOG [HOST]])

Creates and returns a TCP listener object that listens for connections on `TCPPORT`, which should be an exact integer. `BACKLOG` specifies the number of maximally pending connections (and defaults to 4). If the optional argument `HOST` is given and not `#f`, then only incoming connections for the given host (or IP) are accepted.

## tcp-listener?

    [procedure] (tcp-listener? X)

Returns `#t` if `X` is a TCP listener object, or `#f` otherwise.

## tcp-close

    [procedure] (tcp-close LISTENER)

Reclaims any resources associated with `LISTENER`.

## tcp-accept

    [procedure] (tcp-accept LISTENER)

Waits until a connection is established on the port on which `LISTENER` is listening and returns two values: an input- and output-port that can be used to communicate with the remote process.

Note: this operation and any I/O on the ports returned will not block other running threads.

## tcp-accept-ready?

    [procedure] (tcp-accept-ready? LISTENER)

Returns `#t` if there are any connections pending on `LISTENER`, or `#f` otherwise.

## tcp-listener-port

    [procedure] (tcp-listener-port LISTENER)

Returns the port number assigned to `LISTENER` (If you pass `0` to `tcp-listen`, then the system will choose a port-number for you).

## tcp-listener-fileno

    [procedure] (tcp-listener-port LISTENER)

Returns the file-descriptor associated with `LISTENER`.

## tcp-connect

    [procedure] (tcp-connect HOSTNAME [TCPPORT])

Establishes a client-side TCP connection to the machine with the name `HOSTNAME` (a string) at `TCPPORT` (an exact integer) and returns two values: an input- and output-port for communicating with the remote process.

Note: any I/O on the ports returned will not block other running threads.

## tcp-addresses

    [procedure] (tcp-addresses PORT)

Returns two values for the input- or output-port `PORT` (which should be a port returned by either `tcp-accept` or `tcp-connect`): the IP address of the local and the remote machine that are connected over the socket associated with `PORT`. The returned addresses are strings in `XXX.XXX.XXX.XXX` notation.

## tcp-port-numbers

    [procedure] (tcp-port-numbers PORT)

Returns two values for the input- or output-port `PORT` (which should be a port returned by either `tcp-accept` or `tcp-connect`): the TCP port numbers of the local and the remote machine that are connected over the socket associated with `PORT`.

## tcp-abandon-port

    [procedure] (tcp-abandon-port PORT)

Marks the socket port `PORT` as abandoned. This is mainly useful to close down a port without breaking the connection.

## tcp-buffer-size

    [parameter] tcp-buffer-size

Sets the size of the output buffer. By default no output-buffering for TCP output is done, but to improve performance by minimizing the number of TCP packets, buffering may be turned on by setting this parameter to an exact integer greater zero. A buffer size of zero or `#f` turns buffering off. The setting of this parameter takes effect at the time when the I/O ports for a particular socket are created, i.e. when `tcp-connect` or `tcp-accept` is called.

Note that since output is not immediately written to the associated socket, you may need to call `flush-output`, once you want the output to be transmitted. Closing the output port will flush automatically.

# Example

A very simple example follows. Say we have the two files `client.scm` and `server.scm`:

    ; client.scm
    (declare (uses tcp))
    (define-values (i o) (tcp-connect "localhost" 4242))
    (write-line "Good Bye!" o)
    (print (read-line i))

    ; server.scm
    (declare (uses tcp))
    (define l (tcp-listen 4242))
    (define-values (i o) (tcp-accept l))
    (write-line "Hello!" o)
    (print (read-line i))
    (close-input-port i)
    (close-output-port o)

    % csc server.scm
    % csc client.scm
    % ./server &
    % ./client
    Good Bye!
    Hello!

Previous: Unit utils

Next: Unit lolevel