File, directory, network, and other OS/POSIX interfaces

Accessing processes, files, directories, communication pipes and other objects external to a Scheme system

Scanning of a UNIX (POSIX) directory
Obtaining file status information
POSIX interfaces
including inter-process "communication": OS:within-critical-section, as well as reading and writing through TCP, uni- and bidirectional pipes.
Ports and the enhanced i/o
Signals and threads
Network, HTTP and CGI programming [in a separate document]
Reading and writing through Uni-, Bi-directional and TCP pipes as regular files

POSIX interfaces

Version
	A set of native Scheme procedures providing access to the common POSIX library facilities and UNIX system calls: Time and timing `OS:time`, `OS:sleep`, `OS:cftime` (presenting dates and times in various string formats), `OS:string->time` Files and directories `OS:remove`, `OS:rename`, `OS:umask`, `OS:tmpnam`, `OS:file-exists?`, `OS:file-length` `OS:remove-at-exit` `OS:chdir`, `OS:ch-mk-dir`, `OS:ch-parent-dir`, `OS:getcwd` `OS:stderr->file` (redirect the standard error to a file, which is opened in the append mode, and created, if necessary) `OS:ftell`, `OS:fseek-abs` Process/environment queries `OS:getuid`, `OS:geteuid`, `OS:getgid`, `OS:getegid`, `OS:getpid`, `OS:getppid`, `OS:getpgrp` `OS:getenv`, `OS:putenv` Formatting functions `OS:flonum->sprintf`, `OS:int->sprintf` `OS:strtod` Interprocess communication and synchronization `OS:within-critical-section` `OS:within-timeout` `OS:set-keep-alive` `OS:waitpid` Miscellaneous `OS:strerror`, `OS:system` The source code documents the interfaces in full detail.
	The current version is 3.3, Aug 11, 2003.
References
	OS-spec.scm [24K] The commented source code. vipc.scm [2K] Verification of the `OS:within-critical-section` and `OS:within-timeout`. vext-io.scm [15K] Verification of the `OS:remove-at-exit`, and of reading and writing through TCP, uni- and bidirectional pipes. Requires My own standard prelude

Scanning of a `UNIX` `(POSIX)` directory

and getting file status information

-- procedure+: OS:for-each-file-in-directory DIR-NAME PROC

scans through all the files in the given directory, calling procedure PROC on each file
returns a list of PROC's results
The procedure PROC:
- is given a file-info "object" that describes the file being scanned
- if the procedure PROC returns
  - #f, the scanning of the directory is terminated
  - '(), the scanning continues,
    but nothing is added to the list of PROC's results that OS:for-each-file-in-directory accumulates
  - everything else gets appended to the list

The file-info object being given to the procedure PROC is the result of
-- procedure+: OS:make-file-info FILE-PATH

The object accepts the following "messages"

'name: - returns the file's name
'link-count: - returns the link-count of the file
'directory?: - #t if the file is a directory
'block-special?: - #t if the file is a block-special file, like those in /dev/dsk
'char-special?: - #t if the file is a char-special file, as /dev/tty
'regular-file?: - #t if the file is a plain regular file
'pipe?: - #t if the file is a communication (FIFO) pipe
'mtime: - returns the modification time of the file, a BIGNUM, generally, number, the number of seconds since Jan 1, 1970 (see man time(2))
'atime: - returns time of the last (read) access to the file
'ctime: - returns the "creation" time of the file
'size: - returns the file size
'uid: - returns owner's uid
'gid: - returns owner's gid (group id)
'perm: - returns a predicate that takes two symbol arguments, who ('owner, 'group, or 'others) and operation ('read, 'write, or 'exec), and tells if the file can be accessed by who with the operation

All i/o errors raise a ##SIGNAL.IO-ERROR, which can be ##caught.

Verification code vreaddir.scm is a good example of using these functions; note a test case that uses OS:for-each-file-in-directory to fake a "ls -l ." UNIX command

These function use Gambit's Scheme/C foreign function interface.

Current version: Apr 7, 1997
Click to download readdir.scm, and the verification code vreaddir.scm

Ports and the enhanced i/o

Version
	The following higher-level i/o procedures capture several frequently-occurring patterns of input and output. The procedures proved convenient in practice. They are also efficient: Each procedure has a slow and a fast path implementations. The slow path code works with any i/o port and on any R4RS+ Scheme system. The fast path is specific to Gambit and to stream ports. The procedures themselves chose the right (the most optimal) path of execution. `write-substring STR I J PORT` write `(substring STR I J)` into the output `PORT`. If `PORT` is an i/o stream port, an efficient fast path code will be executed. `write-string STR PORT` Write a string `STR` into the output `PORT`, using the `write-substring` procedure above. `port-copy IN-PORT OUT-PORT [NUMBER]` copies characters from an `IN-PORT` to the `OUT-PORT` until the EOF or until the `NUMBER` of characters are copied -- whichever occurs first. The procedure returns the eof-object if EOF was seen; otherwise, it returns 0 (the rest counter). An i/o error signal may be raised as well. If both `IN-PORT` and `OUT-PORT` are stream ports, a highly efficient fast path is used, which does not have to move any data between Scheme and C environments.
	The current version is 3.0, May 2, 2001.
References
	OS-spec.scm [19K] The commented source code. vext-io.scm [15K] Verification code and benchmarks. The benchmarks show that the fast path of `port-copy` can be faster than the slow path by a factor of 100! Requires My own standard prelude

Signals and threads

Version
	Although there is no standard way of handling Unix/Posix signals in Scheme, many implementations, e.g., Gambit, let a user specify a thunk to execute whenever a signal, a timer interrupt or other external condition occurs. Incidentally this makes it possible to write thread scheduling systems and the like directly in Scheme. Indeed, when a signal handler returns the interrupted computation resumes. The signal handler can therefore use its own continuation for thread switching purposes. Listing 1 in the article below shows the example of this idea. It uses non-preemptive "interrupts" and thus should run on every Scheme system. However, if you happen to have a Gambit-C system, you can insert Listing 2 into Listing 1 where indicated. This buys you a preemptive re-scheduling upon arrival of a user-defined signal. You can do "`kill -USR1 pid`" to cause switching from one thread to another.
	The current version is 1.1, Feb 26, 2000.
References
	A USENET article with the complete code and transcripts [plain text file]
From other archives
	comp.lang.scheme newsgroup an article Re: exception handling in scheme posted on Sat Feb 26 02:50:00 2000 GMT

Additions to `Gambit-C`'s foreign function interface

provide the complete mapping between 32-bit C unsigned integers and Scheme numbers. Now, if a C integer turns out to be so big that it does not fit into Scheme's FIXNUM, the corresponding BIGNUM is created. Conversely, both BIGNUM and FIXNUM can be converted to C's unsigned int (if they fit, of course).
Current version: May 3, 1996
Click to download c-intf-add.c

Last updated July 4, 2004

This site's top page is http://okmij.org/ftp/

oleg-at-okmij.org
Your comments, problem reports, questions are very welcome!