6.18.3 File ports

Function: open-input-file filename &keyword if-does-not-exist buffering element-type

Function: open-output-file filename &keyword if-does-not-exist if-exists buffering element-type

[R5RS+] Opens a file filename for input or output, and returns an input or output port associated with it, respectively.

The keyword arguments specify precise behavior on the exceptional case.

:if-exists

This keyword argument can be specified only for open-output-file, and specifies the action when the filename already exists. One of the following value can be given.

:supersede

The existing file is truncated. This is the default behavior.

:append

The output data will be appended to the existing file.

:error

An error is signalled.

#f

No action is taken, and the function returns #f.

:if-does-not-exist

This keyword argument specifies the action when filename does not exist.

:error

An error is signalled. This is the default behavior of open-input-file.

:create

A file is created. This is the default behavior of open-output-file. The check of file existence and creation is done atomically; you can exclusively create the file by specifying :error or #f to if-exists, along this option. You can't specify this value for open-input-file.

#f

No action is taken, and the function returns #f.

:buffering

This argument specifies the buffering mode. The following values are allowed. The port's buffering mode can be get/set by port-buffering. (See section 6.18.2 Common port operations).

:full

Buffer the data as much as possible. This is the default mode.

:none

No buffering is done. Every time the data is written (to an output port) or read (from an input port), the underlying system call is used. Process's standard error port is opened in this mode by default.

:line

This is valid only for output ports. The written data is buffered, but the buffer is flushed whenever a newline character is written. This is suitable for interactive output port. Process's standard output port is opened in this mode by default. (Note that this differs from the line buffering mode of C stdio, which flushes the buffer as well when input is requested from the same file descriptor.)

:modest

This is valid only for input ports. This is almost the same as the mode :full, except that read-block may return less data than requested if the requested amount of data is not immediately available. (In the :full mode, read-block waits the entire data to be read). This is suitable for the port connected to a pipe or network.

:element-type

This argument specifies the type of the file.

:character

The file is opened in "character" (or "text") mode.

:binary

The file is opened in "binary" mode.

In the current version, this argument is ignored and all files are opened in binary mode. It doesn't make difference in the Unix platforms.

By combination of if-exists and if-does-not-exist flags, you can implement various actions:

(open-output-file "foo" :if-exists :error) => ;opens "foo" exclusively, or error (open-output-file "foo" :if-exists #f) => ;opens "foo" exclusively, or returns #f (open-output-file "foo" :if-exists :append :if-does-not-exist :error) => ;opens "foo" for append only if it already exists

To check the existence of a file without opening it, use sys-access or file-exists? (See section 6.21.3.4 File stats).

Note: gauche.charconv module extends these procedures to take encoding keyword argument so that they can read or write in different character encoding scheme. See section 9.2 gauche.charconv - Character Code Conversion.

Note for portability: Some Scheme implementations (e.g. STk) allows you to specify a command to filename and reads from, or writes to, the subprocess standard input/output. Some other scripting languages (e.g. Perl) have similar features. In Gauche, open-input-file and open-output-file strictly operates on files (what the underlying OS thinks as files). However, you can use "process ports" to invoke other command in a subprocess and to communiate it. See section 9.14.2 Process ports, for details.

Function: call-with-input-file string proc &keyword if-exists buffering element-type

Function: call-with-output-file string proc &keyword if-does-not-exist if-exists buffering element-type

[R5RS] Opens a file specified by string for input/output, and call proc with one argument, the file port. When proc returns, or an error is signalled from proc that is not captured within proc, the file is closed.

The keyword arguments if-exists, element-type and if-does-not-exist have the same meanings of open-input-file and open-output-file's. Note that if you specify #f to if-exists and/or if-does-not-exist, proc may receive #f instead of a port object when the file is not opened.

Returns the value(s) proc returned.

Function: with-input-from-file string thunk &keyword if-exists buffering element-type

Function: with-output-to-file string thunk &keyword if-does-not-exist if-exists buffering element-type

[R5RS] Opens a file specified by string for input or output and makes the opened port as the current input or output port, then calls thunk. The file is closed when thunk returns or an error is signalled from thunk that is not captured within thunk.

The keyword arguments have the same meanings of open-input-file and open-output-file's, except that #f is not allowed to if-exists and if-does-not-exist; i.e. an error is always signalled if the file can't be opened.

Returns the value(s) thunk returned.

Notes on semantics of closing file ports: R5RS states, in the description of call-with-input-file et al., that "If proc 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 read or write operation."

Gauche's implementation slightly misses this criteria; the mere fact that an uncaptured error is thrown in proc does not prove the port will never be used. Nevertheless, it is very diffcult to think the situation that you can do meaningful operation on the port after such an error is signalled; you'd have no idea what kind of state the port is in. In practical programs, you should capture error explicitly inside proc if you still want to do some meaningful operation with the port.

Note that if a continuation captured outside call-with-input-file et al. is invoked inside proc, the port is not closed. It is possible that the control returns later into the proc, if a continuation is captured in it (e.g. coroutines). The low-level exceptions (See section 6.16.4 Low-level exception mechanism) also doesn't ensure closing the port.

Function: open-input-fd-port fd &keyword buffering name owner?

Function: open-output-fd-port fd &keyword buffering name owner?

Creates and returns an input or output port on top of the given file descriptor. Buffering specifies the buffering mode as described in open-input-file entry above; the default is :full. Name is used for the created port's name and returned by port-name. A boolean flag owner? specfies whether fd should be closed when the port is closed.