12.1.5 File Ports

A port created by open-input-file, open-output-file, subprocess, and related functions is a file-stream port. The initial input, output, and error ports in racket are also file-stream ports. The file-stream-port? predicate recognizes file-stream ports.

When an input or output file-stream port is created, it is placed into the management of the current custodian (see Custodians).

• 'binary — bytes are returned from the port exactly as they are read from the file.

• 'text — return and linefeed bytes (10 and 13) as read from the file are filtered by the port in a platform specific manner:

  • Unix and Mac OS X: no filtering occurs.

  • Windows: a return-linefeed combination from a file is returned by the port as a single linefeed; no filtering occurs for return bytes that are not followed by a linefeed, or for a linefeed that is not preceded by a return.

Under Windows, 'text mode works only with regular files; attempting to use 'text with other kinds of files triggers an exn:fail:filesystem exception.

Otherwise, the file specified by path need not be a regular file. It might a device that is connected through the filesystem, such as "aux" under Windows or "/dev/null" under Unix. In all cases, the port is buffered by default.

The port produced by open-input-file should be explicitly closed, either though close-input-port or indirectly via custodian-shutdown-all, to release the OS-level file handle. The input port will not be closed automatically if it is otherwise available for garbage collection (see Garbage Collection); a will could be associated input port to close it more automatically (see Wills and Executors).

A path value that is the cleansed version of path is used as the name of the opened port.

Examples:

> (with-output-to-file some-file       (lambda () (printf "hello world")))

(define in (open-input-file some-file))

> (read-string 11 in)

"hello world"

> (close-input-port in)

• 'binary — bytes are written to the file exactly as written to the port.

• 'text — under Windows, a linefeed byte (10) written to the port is translated to a return-linefeed combination in the file; no filtering occurs for returns.

Under Windows, 'text mode works only with regular files; attempting to use 'text with other kinds of files triggers an exn:fail:filesystem exception.

The exists-flag argument specifies how to handle/require files that already exist:

• 'error — raise exn:fail:filesystem if the file exists.

• 'replace — remove the old file, if it exists, and write a new one.

• 'truncate — remove all old data, if the file exists.

• 'must-truncate — remove all old data in an existing file; if the file does not exist, the exn:fail:filesystem exception is raised.

• 'truncate/replace — try 'truncate; if it fails (perhaps due to file permissions), try 'replace.

• 'update — open an existing file without truncating it; if the file does not exist, the exn:fail:filesystem exception is raised. Use file-position to change the current read/write position.

• 'can-update — open an existing file without truncating it, or create the file if it does not exist.

• 'append — append to the end of the file, whether it already exists or not; under Windows, 'append is equivalent to 'update, except that the file is not required to exist, and the file position is immediately set to the end of the file after opening it.

The file specified by path need not be a regular file. It might a device that is connected through the filesystem, such as "aux" under Windows or "/dev/null" under Unix. The output port is block-buffered by default, unless the file corresponds to a terminal, in which case is it line buffered bu default.

The port produced by open-output-port should be explicitly closed, either though close-output-port or indirectly via custodian-shutdown-all, to release the OS-level file handle. The output port will not be closed automatically if it is otherwise available for garbage collection (see Garbage Collection); a will could be associated input port to close it more automatically (see Wills and Executors).

A path value that is the cleansed version of path is used as the name of the opened port.

Examples:

(define out (open-output-file some-file))

> (write "hello world" out)

> (close-output-port out)

Examples:

> (with-output-to-file some-file       (lambda () (printf "text in a file")))

> (call-with-input-file some-file       (lambda (in) (read-string 15 in)))

"text in a file"

Examples:

> (call-with-output-file some-file       (lambda (out)         (write 'hello out)))

> (call-with-input-file some-file       (lambda (in)         (read-string 5 in)))

"hello"

Examples:

> (with-output-to-file some-file       (lambda () (printf "hello")))

> (with-input-from-file some-file       (lambda () (read-string 5)))

"hello"

Examples:

> (with-output-to-file some-file       (lambda () (printf "hello")))

> (with-input-from-file some-file       (lambda () (read-string 5)))

"hello"

The result is #t if the requested lock is acquired, #f otherwise. When a lock is acquired, it is held until either it is released with port-file-unlock or the port is closed (perhaps because the process terminates).

Depending on the platform, locks may be merely advisory (i.e., locks affect only the ability of processes to acquire locks) or they may correspond to mandatory locks that prevent reads and writes to the locked file. Specifically, locks are mandatory under Windows and advisory on other platforms.

Typically, locking is supported only for file ports, and attempting to acquire a lock with other kinds of file-stream ports raises an exn:fail:filesystem exception.

Examples:

(define file1 (open-output-file some-file))

(define file2 (open-output-file some-other-file))

> (port-file-identity file1)

805469696

> (port-file-identity file2)

805704448

> (close-output-port file1)

> (close-output-port file2)