## Module (chicken tcp)

This module provides basic facilities for communicating over TCP sockets.

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

### tcp-listen

tcp-listen TCPPORT #!optional BACKLOG HOSTprocedure

  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 100). If the optional argument HOST is given and not `#f`, then only incoming connections for the given host (or IP) are accepted.

### tcp-listener?

tcp-listener? Xprocedure

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

### tcp-close

tcp-close LISTENERprocedure

  Reclaims any resources associated with LISTENER.

### tcp-accept

tcp-accept LISTENERprocedure

  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. The current value of `tcp-accept-timeout` is used to determine the maximal number of milliseconds (if any) to wait until a connection is established. When a client connects any read- and write-operations on the returned ports will use the current values (at the time of the connection) of `tcp-read-timeout` and `tcp-write-timeout`, respectively, to determine the maximal number of milliseconds to wait for input/output before a timeout error is signalled.

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

### tcp-accept-ready?

tcp-accept-ready? LISTENERprocedure

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

### tcp-listener-port

tcp-listener-port LISTENERprocedure

  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

tcp-listener-fileno LISTENERprocedure

  Returns the file-descriptor associated with LISTENER.

### tcp-connect

tcp-connect HOSTNAME #!optional TCPPORTprocedure

  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. The current value of `tcp-connect-timeout` is used to determine the maximal number of milliseconds (if any) to wait until the connection is established. When the connection takes place any read- and write-operations on the returned ports will use the current values (at the time of the call to `tcp-connect`) of `tcp-read-timeout` and `tcp-write-timeout`, respectively, to determine the maximal number of milliseconds to wait for input/output before a timeout error is signalled.

  If the TCPPORT is omitted, the port is parsed from the HOSTNAME string. The format expected is `HOSTNAME:PORT`. The `PORT` can either be a string representation of an integer or a service name which is translated to an integer using the POSIX function `getservbyname`.

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

### tcp-addresses

tcp-addresses PORTprocedure

  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

tcp-port-numbers PORTprocedure

  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

tcp-abandon-port PORTprocedure

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

### tcp-buffer-size

tcp-buffer-sizeparameter

  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.

### tcp-read-timeout

tcp-read-timeoutparameter

  Determines the timeout for TCP read operations in milliseconds. A timeout of `#f` disables timeout checking. The default read timeout is 60000, i.e. 1 minute. If timeout occurs while reading, a condition object of kinds `(exn i/o net timeout)` is thrown.

### tcp-write-timeout

tcp-write-timeoutparameter

  Determines the timeout for TCP write operations in milliseconds. A timeout of `#f` disables timeout checking. The default write timeout is 60000, i.e. 1 minute. If timeout occurs while writing, a condition object of kinds `(exn i/o net timeout)` is thrown.

### tcp-connect-timeout

tcp-connect-timeoutparameter

  Determines the timeout for `tcp-connect` operations in milliseconds. A timeout of `#f` disables timeout checking and is the default. If timeout occurs while trying to connect, a condition object of kinds `(exn i/o net timeout)` is thrown.

### tcp-accept-timeout

tcp-accept-timeoutparameter

  Determines the timeout for `tcp-accept` operations in milliseconds. A timeout of `#f` disables timeout checking and is the default. If timeout occurs while waiting for connections, a condition object of kinds `(exn i/o net timeout)` is thrown.

### Example

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

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

    ; server.scm
    (import (chicken io) (chicken 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: Module (chicken syntax)

Next: Module (chicken time)