Node:File Ports, Next:, Up:Port Types


27.9.1 File Ports

The following procedures are used to open file ports. See also open, for an interface to the Unix open system call.

open-file filename mode Scheme Procedure
scm_open_file (filename, mode) C Function
Open the file whose name is filename, and return a port representing that file. The attributes of the port are determined by the mode string. The way in which this is interpreted is similar to C stdio. The first character must be one of the following:
r
Open an existing file for input.
w
Open a file for output, creating it if it doesn't already exist or removing its contents if it does.
a
Open a file for output, creating it if it doesn't already exist. All writes to the port will go to the end of the file. The "append mode" can be turned off while the port is in use see fcntl
The following additional characters can be appended:
+
Open the port for both input and output. E.g., r+: open an existing file for both input and output.
0
Create an "unbuffered" port. In this case input and output operations are passed directly to the underlying port implementation without additional buffering. This is likely to slow down I/O operations. The buffering mode can be changed while a port is in use see setvbuf
l
Add line-buffering to the port. The port output buffer will be automatically flushed whenever a newline character is written.
In theory we could create read/write ports which were buffered in one direction only. However this isn't included in the current interfaces. If a file cannot be opened with the access requested, open-file throws an exception.

open-input-file filename Scheme Procedure
Open filename for input. Equivalent to 
(open-file filename "r")

open-output-file filename Scheme Procedure
Open filename for output. Equivalent to 
(open-file filename "w")

call-with-input-file file proc Scheme Procedure
proc should be a procedure of one argument, and file should be a string naming a file. The file must already exist. These procedures call proc with one argument: the port obtained by opening the named file for input or output. If the file cannot be opened, an error is signalled. If the procedure returns, then the port is closed automatically and the value yielded by the procedure is returned. If the procedure does not return, then the port will not be closed automatically unless it is possible to prove that the port will never again be used for a read or write operation.

call-with-output-file file proc Scheme Procedure
proc should be a procedure of one argument, and file should be a string naming a file. The behaviour is unspecified if the file already exists. These procedures call proc with one argument: the port obtained by opening the named file for input or output. If the file cannot be opened, an error is signalled. If the procedure returns, then the port is closed automatically and the value yielded by the procedure is returned. If the procedure does not return, then the port will not be closed automatically unless it is possible to prove that the port will never again be used for a read or write operation.

with-input-from-file file thunk Scheme Procedure
thunk must be a procedure of no arguments, and file must be a string naming a file. The file must already exist. The file is opened for input, an input port connected to it is made the default value returned by current-input-port, and the thunk is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. Returns the value yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, their behavior is implementation dependent.

with-output-to-file file thunk Scheme Procedure
thunk must be a procedure of no arguments, and file must be a string naming a file. The effect is unspecified if the file already exists. The file is opened for output, an output port connected to it is made the default value returned by current-output-port, and the thunk is called with no arguments. When the thunk returns, the port is closed and the previous default is restored. Returns the value yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, their behavior is implementation dependent.

with-error-to-file file thunk Scheme Procedure
thunk must be a procedure of no arguments, and file must be a string naming a file. The effect is unspecified if the file already exists. 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. Returns the value yielded by thunk. If an escape procedure is used to escape from the continuation of these procedures, their behavior is implementation dependent.

port-mode port Scheme Procedure
scm_port_mode (port) C Function
Return the port modes associated with the open port port. These will not necessarily be identical to the modes used when the port was opened, since modes such as "append" which are used only during port creation are not retained.

port-filename port Scheme Procedure
scm_port_filename (port) C Function
Return the filename associated with port. This function returns the strings "standard input", "standard output" and "standard error" when called on the current input, output and error ports respectively.

set-port-filename! port filename Scheme Procedure
scm_set_port_filename_x (port, filename) C Function
Change the filename associated with port, using the current input port if none is specified. Note that this does not change the port's source of data, but only the value that is returned by port-filename and reported in diagnostic output.

file-port? obj Scheme Procedure
scm_file_port_p (obj) C Function
Determine whether obj is a port that is related to a file.