TinyScheme with I/O Event Dispatcher and Network Extensions (TSION)

    #include  "tsion.h"			/* TinyScheme I/O Network functions. */

    ...

    /* Create the Scheme engine. */

        scheme  sc = scheme_init_new ();

    /* Load the initialization file. */

        FILE  *file = fopen ("init.scm", "r") ;
        scheme_load_file (sc, file) ;
        fclose (file) ;

    /* Add the TSION extensions. */

        addFuncsDRS (sc) ;
        addFuncsIOX (sc) ;
        addFuncsLFN (sc) ;
        addFuncsMISC (sc) ;
        addFuncsNET (sc) ;
        addFuncsREX (sc) ;
        addFuncsSKT (sc) ;
        addFuncsTCP (sc) ;

        ...

— Scheme Function: (net-addr "host")

Lookup host and return its IP address as an integer in network-byte-order.

— Scheme Function: (net-host IP-address [dotted?])

Lookup IP-address (an integer in network-byte-order) and return the corresponding host name string. If dotted? is present and #f, the address is returned in dotted IP format; otherwise, the host name is returned.

— Scheme Function: (net-port "service" [udp?])

Lookup service in the network services database (the "/etc/services" file) and return the corresponding port number. If udp? is present and #t, the UDP port is returned; otherwise, the TCP port is returned.

— Scheme Function: (skt-startup)
— Scheme Function: (skt-cleanup)

Startup and shutdown the socket library; return #t upon success and #f otherwise. These functions are not needed on most platforms.

— Scheme Function: (skt-peer fd)

Determine the host at the other end of network socket connection fd and returns its IP address as an integer in network-byte-order; #f is returned in the event of an error.

— Scheme Function: (skt-port fd)

Get the number of the port to which socket fd is bound; #f is returned in the event of an error.

— Scheme Function: (skt-readable? fd)
— Scheme Function: (skt-up? fd)
— Scheme Function: (skt-writeable? fd)

Check if

• data is waiting to be read from socket fd,
• fd's network connection is still up, and
• data can be written to fd, respectively.

Return #t if the predicate is true and #f otherwise.

— Scheme Function: (skt-setbuf fd recvSize sendSize)

Set the size of socket fd's receive buffer to recvSize bytes and the size of its send buffer to sendSize bytes. If a buffer size is less than zero, the respective buffer retains its current size. Return #t if the buffer sizes were modified successfully and #f otherwise.

— Scheme Function: (tcp-listen "service"|port [backlog])
— Scheme Function: (tcp-answer endpoint [timeout])

The first function creates a "listening" endpoint bound to the named service port at which the application will listen for connection requests from clients. (Alternatively, you may specify the port number directly.) At most backlog requests may be pending; if this argument is not specified, a platform-specific maximum is used. An opaque handle for the listening endpoint is returned for use in subsequent calls to tcp-answer; #f is returned in the event of an error.

The second function, tcp-answer, waits at most timeout seconds for a connection request to be received on the listening endpoint (previously returned by tcp-listen). If a request is received, accept the request. The operating system automatically creates a new endpoint (the "data" endpoint) through which the server can talk to the client. An opaque handle is returned for the new data endpoint; #f is returned in the event of an error.

— Scheme Function: (tcp-call "service[@host]"|port [noWait?])
— Scheme Function: (tcp-complete endpoint [timeout [destroy?])

The first function, tcp-call, requests a network connection to the server at "service[@host]". (Alternatively, you may specify a port number on the local host.) If the noWait? flag is not present or is #f, tcp-call waits until the connection is established (or refused) before returning. If the noWait? flag is #t, tcp-call initiates the connection attempt and returns immediately; the application should subsequently invoke tcp-complete to complete the connection. In all cases, an opaque handle for the data endpoint is returned; #f is returned in the event of an error.

The second function, tcp-complete, waits for an asynchronous, network connection attempt to complete (if it is fated to complete).

The function will wait at most timeout seconds for the call to complete. If this argument is not present or is negative, tcp-complete will wait as long as necessary. A timeout of zero seconds causes an immediate return if the connection is not yet established.

If the connection attempt times out or otherwise fails and destroy? is not present or is #t, endpoint will automatically be destroyed. This mode is useful when the application plans to make a single go/no-go call to tcp-complete.

If, under the same circumstances, destroy? is #f, endpoint will not be destroyed; the application is responsible for executing tcp-destroy explicitly in the event of an error. This mode is useful when the application plans to periodically call tcp-complete (perhaps with a timeout of zero) until the connection is successfully established.

If a connection is not (or not yet) successfully established, #f is returned.

— Scheme Function: (tcp-debug value)

Set the TCP/IP networking debug flag to value, an integer number. A value of 0 disables debug; a non-zero value enables debug. Debug is written to standard output.

— Scheme Function: (tcp-destroy endpoint)

Close a listening or data endpoint; endpoint should no longer be referenced.

— Scheme Function: (tcp-fd endpoint)

Get endpoint's socket; endpoint may be a listening or a data endpoint. The socket is an integer; in the event of an error, #f is returned.

— Scheme Function: (tcp-name endpoint)

Return endpoint's name as a string. The name is in one of three formats:

• "port" - if endpoint is a listening point,
• "port#host" - if endpoint is a server-side connection (i.e., created by tcp-answer), or
• "port@host" - if endpoint is a client-side connection (i.e., created by tcp-call).

— Scheme Function: (tcp-pending? endpoint)
— Scheme Function: (tcp-readable? endpoint)
— Scheme Function: (tcp-up? endpoint)
— Scheme Function: (tcp-writeable? endpoint)

Check if

• any connection requests from potential clients are waiting to be answered on listening endpoint,
• data is waiting to be read from endpoint,
• endpoint's network connection is still up, and
• data can be written to endpoint, respectively.

Return #t if the predicate is true and #f otherwise.

— Scheme Function: (tcp-read endpoint length [timeout])

Read length bytes of arbitrary data from endpoint into a string buffer and return the buffer to the caller. The data can be arbitrary binary data and can contain embedded NULs.

Because of the way network I/O works, a single record written to a connection by one task may be read in multiple "chunks" by the task at the other end of the connection. This is taken into account by tcp-read and, if you ask it for 100 bytes, it will automatically perform however many network reads are necessary to collect the 100 bytes.

If length is negative, tcp-read returns after reading the first "chunk" of input received; the number of bytes read from that first "chunk" is limited to the absolute value of length. The actual string of bytes read is returned to the caller.

The function will wait at most timeout seconds for the first data to arrive. If timeout is not present or is negative, tcp-read will wait as long as necessary to read the requested amount of data. A timeout of zero allows a read only if input is immediately available. If timeout is specified and is greater than zero, tcp-read will return the amount of data actually read when timeout expires. Finally, in the event of an error, #f is returned.

— Scheme Function: (tcp-write endpoint string [timeout])

Write arbitrary data from a string to endpoint.

Because of the way network I/O works, attempting to output a given amount of data to a network connection may require multiple network writers. This is taken into account by tcp-write and, if you ask it to output 100 bytes, it will perform however many network writes are necessary to output the full 100 bytes of data to the connection.

The funcction will wait at most timeout seconds for the data to be output. If this argument is not present or is negative, tcp-write will wait as long as necessary to output all of the data. A zero timeout specifies no wait: if endpoint is not ready for writing, tcp-write returns immediately. If the connection is ready for writing, tcp-write returns after outputting whatever it can.

If timeout is present and positive, tcp-write outputs whatever it can in the given time interval. In all cases, the number of bytes actually written is returned to the caller; #f is returned in the event of an error.

— Scheme Function: (lfn-create endpoint [options])

Create a LF-terminated network stream on top of the previously-created TCP/IP endpoint. The stream takes ownership of endpoint, which will automatically be destroyed when the stream is destroyed. The stream is returned as an opaque handle to the caller.

The optional options string contains zero or more of the following UNIX command line-style options:

"-input size"

specifies the size of the stream's internal input buffer; the default is 2048 bytes. NOTE that this is only a limit on the input buffer, not on incoming strings.

"-output length"

specifies the maximum output message size for the stream; the default is 2047 bytes.

— Scheme Function: (lfn-debug value)

Set the LF-terminated networking debug flag to value, an integer number. A value of 0 disables debug; a non-zero value enables debug. Debug is written to standard output.

— Scheme Function: (lfn-destroy stream)

Close LF-terminated network stream and its underlying TCP/IP endpoint; stream should no longer be referenced.

— Scheme Function: (lfn-fd stream)

Get stream's socket. The socket is an integer; in the event of an error, #f is returned.

— Scheme Function: (lfn-name stream)

Return stream's name as a string. The name is in one of two formats:

• "port#host" - if the stream's underlying TCP/IP endpoit is a server-side connection or
• "port@host" - if the underlying endpoint is a client--side connection.

— Scheme Function: (lfn-readable? stream)
— Scheme Function: (lfn-up? stream)
— Scheme Function: (lfn-writeable? stream)

Check if

• data (either buffered or outstanding on the socket) is waiting to be read from stream,
• stream's network connection is still up, and
• data can be written to stream, respectively.

Return #t if the predicate is true and #f otherwise. NOTE that LF-terminated input is buffered, so an application must keep reading and processing lines of input until lfn-readable? returns #f.

— Scheme Function: (lfn-getline stream [timeout])

Read the next CR/LF-delimited line of input from stream and return the input as a string with the line terminators removed; #f is returned in the event of an error.

The function will wait at most timeout seconds for buffered or pending socket data to be available. If timeout is not present or is negative, lfn-getline will wait as long as necessary to read the next line of input; a timeout of zero allows a read only if input is immediately available. If timeout is specified and is greater than zero, lfn-getline will wait that many seconds for the first piece of data to become available. Once the first data arrives, lfn-getline will take as long as necessary to read a full line of input, regardless of the timeout.

— Scheme Function: (lfn-putline stream string [crlf [timeout]])

Write a line of output, string, to stream; #t is returned if the write is successful and #f otherwise.

Optional bit mask crlf specifies line terminators to be appended to the output string: 0 = no terminator, 1 = LF only, 2 = CR only, and 3 = CR/LF. Zero (the default if this argument is not present) is typically used if the application explicitly puts the line terminators in the output string.

The funcction will wait at most timeout seconds to begin writing string. If this argument is not present or is negative, lfn-putline will wait as long as necessary to output all of the data. A zero timeout specifies no wait: if stream is not ready for writing, lfn-putline returns immediately. If the connection is ready for writing, lfn-putline returns after writing the entire string.

If timeout is present and positive, lfn-putline will wait that many seconds to begin writing string. Once output begins, lfn-putline will continue to write the entire string, regardless of the timeout value.

— Scheme Function: (lfn-read stream length [timeout])

Read length bytes of arbitrary data from stream into a string buffer and return the buffer to the caller. The data can be arbitrary binary data and can contain embedded NULs.

Because of the way network I/O works, a single record written to a connection by one task may be read in multiple "chunks" by the task at the other end of the connection. This is taken into account by lfn-read and, if you ask it for 100 bytes, it will automatically perform however many network reads are necessary to collect the 100 bytes.

If length is negative, lfn-read returns after reading the first "chunk" of input received; the number of bytes read from that first "chunk" is limited to the absolute value of length. The actual string of bytes read is returned to the caller.

The function will wait at most timeout seconds for the first data to arrive. If timeout is not present or is negative, lfn-read will wait as long as necessary to read the requested amount of data. A timeout of zero allows a read only if input is immediately available. If timeout is specified and is greater than zero, lfn-read will return the amount of data actually read when timeout expires. Finally, in the event of an error, #f is returned.

— Scheme Function: (lfn-write stream string [timeout])

Write arbitrary data from string to stream.

Because of the way network I/O works, attempting to output a given amount of data to a network connection may require multiple network writers. This is taken into account by lfn-write and, if you ask it to output 100 bytes, it will perform however many network writes are necessary to output the full 100 bytes of data to the connection.

The funcction will wait at most timeout seconds for the data to be output. If this argument is not present or is negative, lfn-write will wait as long as necessary to output all of the data. A zero timeout specifies no wait: if stream is not ready for writing, lfn-write returns immediately. If the connection is ready for writing, lfn-write returns after outputting whatever it can.

If timeout is present and positive, lfn-write outputs whatever it can in the given time interval. In all cases, the number of bytes actually written is returned to the caller; #f is returned in the event of an error.

    (function callback userData reason)

— Scheme Function: (iox-create)

Create an I/O event dispatcher. An opaque handle is returned for the dispatcher; #f is returned in the event of an error.

 

---

Directory Scanning Functions

The DRS group consists of functions used to scan lists of files in directories.

Source: funcs_drs.c