4.6.1 Opening and Closing

Function: open-file string modes ¶

Function: try-open-file string modes ¶

Returns a port capable of receiving or delivering characters as specified by the modes string. If a file cannot be opened #f is returned.

Internal functions opening files callback to the SCM function open-file. You can extend open-file by redefining it. try-open-file is the primitive procedure; Do not redefine try-open-file!

Constant: open_read ¶

Constant: open_write ¶

Constant: open_both ¶

Contain modes strings specifying that a file is to be opened for reading, writing, and both reading and writing respectively.

Both input and output functions can be used with io-ports. An end of file must be read or a two-argument file-position done on the port between a read operation and a write operation or vice-versa.

Function: _ionbf modestr ¶

Returns a version of modestr which when open-file is called with it as the second argument will return an unbuffered port. An input-port must be unbuffered in order for char-ready? and wait-for-input to work correctly on it. The initial value of (current-input-port) is unbuffered if the platform supports it.

Function: _tracked modestr ¶

Returns a version of modestr which when open-file is called with it as the second argument will return a tracked port. A tracked port maintains current line and column numbers, which may be queried with port-line and port-column.

Function: _exclusive modestr ¶

Returns a version of modestr which when open-file is called with it as the second argument will return a port only if the named file does not already exist. This functionality is provided by calling try-create-file See I/O-Extensions, which is not available for all platforms.

Function: open-ports ¶

Returns a list of all currently open ports, excluding string ports, see See String Ports in SLIB. This may be useful after a fork See Posix Extensions, or for debugging. Bear in mind that ports that would be closed by gc will be kept open by a reference to this list.

Function: close-port port ¶

Closes port. The same as close-input-port and close-output-port.

---

4.6.2 Port Properties

Function: port-closed? port ¶

Returns #t if port is closed.

Function: port-type obj ¶

If obj is not a port returns false, otherwise returns a symbol describing the port type, for example string or pipe.

Function: port-filename port ¶

Returns the filename port was opened with. If port is not open to a file the result is unspecified.

Function: file-position port ¶

Function: file-position port #f ¶

Returns the current position of the character in port which will next be read or written. If port is open to a non-file then #f is returned.

Function: file-position port k ¶

Sets the current position in port which will next be read or written. If successful, #f is returned. If port is open to a non-file, then file-position returns #f.

Function: port-line port ¶

Function: port-column port ¶

If port is a tracked port, return the current line (column) number, otherwise return #f. Line and column numbers begin with 1. The column number applies to the next character to be read; if that character is a newline, then the column number will be one more than the length of the line.

Function: freshline port ¶

Outputs a newline to optional argument port unless the current output column number of port is known to be zero, ie output will start at the beginning of a new line. port defaults to current-output-port. If port is not a tracked port freshline is equivalent to newline.

Function: isatty? port ¶

Returns #t if port is input or output to a serial non-file device.

procedure: char-ready? ¶

procedure: char-ready? port ¶

Returns #t if a character is ready on the input port and returns #f otherwise. If char-ready? returns #t then the next read-char operation on the given port is guaranteed not to hang. If the port is at end of file then char-ready? returns #t. Port may be omitted, in which case it defaults to the value returned by current-input-port.

Rationale Char-ready? exists to make it possible for a program to accept characters from interactive ports without getting stuck waiting for input. Any input editors associated with such ports must ensure that characters whose existence has been asserted by char-ready? cannot be rubbed out. If char-ready? were to return #f at end of file, a port at end of file would be indistinguishable from an interactive port that has no ready characters.

procedure: wait-for-input x ¶

procedure: wait-for-input x port1 … ¶

Returns a list those ports port1 … which are char-ready?. If none of port1 … become char-ready? within the time interval of x seconds, then #f is returned. The port1 … arguments may be omitted, in which case they default to the list of the value returned by current-input-port.

---

4.6.3 Port Redirection

Function: current-error-port ¶

Returns the current port to which diagnostic output is directed.

Function: with-error-to-file string thunk ¶

thunk must be a procedure of no arguments, and string must be a string naming a file. The file is opened for output, an output port connected to it is made the default value returned by current-error-port, and the thunk is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. With-error-to-file returns the value yielded by thunk.

Function: with-input-from-port port thunk ¶

Function: with-output-to-port port thunk ¶

Function: with-error-to-port port thunk ¶

These routines differ from with-input-from-file, with-output-to-file, and with-error-to-file in that the first argument is a port, rather than a string naming a file.

Function: call-with-outputs thunk proc ¶

Calls the thunk procedure while the current-output-port and current-error-port are directed to string-ports. If thunk returns, the proc procedure is called with the output-string, the error-string, and the value returned by thunk. If thunk does not return a value (perhaps because of error), proc is called with just the output-string and the error-string as arguments.

---

4.6.4 Soft Ports

A soft-port is a port based on a vector of procedures capable of accepting or delivering characters. It allows emulation of I/O ports.

Function: make-soft-port vector modes ¶

Returns a port capable of receiving or delivering characters as specified by the modes string (see open-file). vector must be a vector of length 5. Its components are as follows:

0. procedure accepting one character for output
1. procedure accepting a string for output
2. thunk for flushing output
3. thunk for getting one character
4. thunk for closing port (not by garbage collection)

For an output-only port only elements 0, 1, 2, and 4 need be procedures. For an input-only port only elements 3 and 4 need be procedures. Thunks 2 and 4 can instead be #f if there is no useful operation for them to perform.

If thunk 3 returns #f or an eof-object (see eof-object? in Revised(5) Scheme) it indicates that the port has reached end-of-file. For example:

If it is necessary to explicitly close the port when it is garbage collected, (see add-finalizer).

(define stdout (current-output-port))
(define p (make-soft-port
           (vector
            (lambda (c) (write c stdout))
            (lambda (s) (display s stdout))
            (lambda () (display "." stdout))
            (lambda () (char-upcase (read-char)))
            (lambda () (display "@" stdout)))
           "rw"))

(write p p) ⇒ #<input-output-soft#\space45d10#\>