6.  Low-Level I/O, File Descriptors  

(unix-close fdescr)

The UNIX close() system call. unix-close returns the non-printing object.

(unix-dup fdescr)
(unix-dup fdescr1 fdescr2)

unix-dup invokes the dup() (first form) or dup2() (second form) system call. The result is a new file descriptor (an integer).

(unix-open filename flags)
(unix-open filename flags mode)

The UNIX open() system call. flags is a list of one or more symbols specifying the bitmask argument of the open() system call.

At least the flag symbols read, write, append, create, truncate, and exclusive are supported; additional symbols (such as ndelay) may be permitted on certain platforms. The procedure unix-list-open-modes can be used to obtain the list of flag symbols that are supported (see below). If create is present in the flags argument, the mode argument (an integer) must be supplied. At least one of the symbols read or write must be present in flags.

unix-open returns a new file descriptor (an integer).

Example:

(let ((f1 (unix-open "/etc/passwd" '(read))
      (f2 (unix-open "temp" '(read write create truncate) #o666))))
  ...)

(unix-list-open-modes)

This procedure returns the list of flag symbols for the unix-open procedure that are supported on the local platform.

(unix-lseek fdescr offset whence)

The UNIX lseek() system call. offset is an integer; whence is one of the symbols set, current, and end. unix-lseek returns the new file position as an integer.

(unix-pipe)

The pipe() system call. unix-pipe returns two file descriptors as a pair of integers.

(unix-read-string-fill! fdescr string)
(unix-read-string-fill! fdescr string length)

The read() system call. unix-read-string-fill invokes read() with the Scheme string as input buffer and the length of the string argument (first form) or the length supplied as a third argument (second form). If length is specified, it must be an integer between 0 and the length of string.

unix-read-string-fill! destructively overwrites the contents of the string argument. It returns the number of characters actually read (0 on EOF).

(unix-write fdescr string)
(unix-write fdescr string length)

The write() system call. For a description of the arguments see unix-read-string-fill! above. unix-write returns the number of characters actually written.

(unix-close-on-exec fdescr)
(unix-close-on-exec fdescr on?)

unix-close-on-exec returns the value of the close-on-exec flag for the given file descriptor as a boolean. If invoked with a second argument, the procedure sets the close-on-exec flag to the specified value and returns the previous value.

(unix-filedescriptor-flags fdescr)
(unix-filedescriptor-flags fdescr flags)

unix-file-descriptor-flags obtains the flags currently active for the given file descriptor (by means of the fcntl() system call) and returns them as a list of symbols. If invoked with a second arguments (a list of symbols), the procedure sets the flags to that argument and returns the previous value.

At least the flag symbol append is supported; additional symbols (such as ndelay or sync) may be permitted on certain platforms. The procedure unix-list-filedescriptor-flags can be used to obtain the list of file descriptor flags that are supported (see below).

Example:

;;; Enable non-blocking I/O for file descriptor (assumes POSIX)
(define (set-non-blocking fd)
  (let ((flags (unix-filedescriptor-flags fd)))
    (unix-filedescriptor-flags fd (cons 'nonblock flags))))

(unix-list-filedescriptor-flags)

This procedure returns the list of file descriptor flag symbols that can be returned and set by unix-filedescriptor-flags on the local platform.

(unix-num-filedescriptors)

unix-num-filedescriptors returns the maximum number of file descriptors per process in the local system. Depending on the UNIX flavor, the procedure invokes getdtablesize() or sysconf() or uses a static (compile-time) limit.

(unix-isatty? fdescr)

Returns #t if the specified file descriptor points to a terminal device, #f otherwise (the UNIX isatty() library function).

(unix-ttyname fdescr)

The UNIX ttyname() function. Returns the name of a terminal device as a string, or #f if the file descriptor is not associated with a terminal.

(unix-port-filedescriptor port)

This procedure returns the file descriptor associated with the file pointer conveyed in the specified Scheme port. An error is signaled if the port has already been closed or if it is a string port. unix-port-filedescriptor invokes the UNIX fileno() library function.

Manipulating a file descriptor obtained by unix-port-filedescriptor can cause unexpected interactions with the standard Scheme I/O functions and with the stdio buffering mechanism. In particular, it is not a good idea to close the file descriptor associated with the Scheme system's current input port or current output port.

Example:

(let ((stdout-fileno
        (unix-port-filedescriptor (current-output-port))))
  (if (unix-isatty? stdout-fileno)
      (begin
        (display (unix-ttyname stdout-fileno))
        (newline))))

(unix-filedescriptor->port fdescr type)

Creates a Scheme port with a file pointer containing the specified file descriptor. unix-filedescriptor->port is based on the fdopen() stdio function. type is a string and is used as the second argument for fdopen().

The type of the newly created Scheme port is determined by the type argument. If type begins with the character #\r, an input port is created; #\w and #\a indicate an output port. If the second character of type is #\+ (update), an input-output (bidirectional) port is created.

No filename is associated with a Scheme port created by a call to unix-filedescriptor->port. Instead, the string unix-filedescriptor[%d] (where %d is replaced by the numerical value of the file descriptor) will be returned by calls to port-file-name and displayed when printing the port.

Note that the file descriptor is closed by the garbage collector when the Scheme port becomes inaccessible.


Markup created by unroff 1.0,    September 24, 1996,    net@informatik.uni-bremen.de