13.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). In the case of an output port, a flush callback is registered with the current plumber to flush the port.

• '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: 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.

On 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 be a device that is connected through the filesystem, such as "aux" on Windows or "/dev/null" on 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 with an 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.

If opening the file fails due to an error in the filesystem, then exn:fail:filesystem:errno exception is raised—as long as for-module? is #f, current-module-path-for-load has a non-#f value, or the filesystem error is not recognized as a file-not-found error. Otherwise, when for-module? is true, current-module-path-for-load has a non-#f value, and the filesystem error is recognized as a file-not-found error, then the raised exception is either exn:fail:syntax:missing-module (if the value of current-module-path-for-load is a syntax object) or exn:fail:filesystem:missing-module (otherwise).

Changed in version 6.0.1.6 of package base: Added #:for-module?.

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

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

On 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; on 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.

When the file specified by path is created, permissions specifies the permissions of the created file, where an integer representation of permissions is treated the same as for file-or-directory-permissions. On Unix and Mac OS, these permissions bits are combined with the process’s umask. On Windows, the only relevant property of permissions is whether it has the #o2 bit set for write permission. Note that a read-only file can be created with open-output-file, in which case writing is prohibited only for later attempts to open the file. If replace-permissions? is a true value, then independent of whether the opened file is newly created, the value of permissions is applied to the opened file, and it is applied independent of the process’s umask on Unix and Mac OS.

The file specified by path need not be a regular file. It might be a device that is connected through the filesystem, such as "aux" on Windows or "/dev/null" on Unix. The output port is block-buffered by default, unless the file corresponds to a terminal, in which case it is line-buffered by default. On Unix and Mac OS, if the file is a fifo, then the port will block for writing until a reader for the fifo is available; see also port-waiting-peer?.

The port produced by open-output-file 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 with an output 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.

If opening the file fails due to an error in the underlying filesystem then exn:fail:filesystem:errno exception is raised.

Changed in version 6.9.0.6 of package base: On Unix and Mac OS, make 'truncate/replace replace on a permission error. On Windows, make 'replace always replace instead truncating like 'truncate/replace.
Changed in version 7.4.0.5: Changed handling of a fifo on Unix and Mac OS to make the port block for output until the fifo has a reader.
Changed in version 8.1.0.3: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.

Changed in version 8.1.0.3 of package base: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.

Changed in version 8.1.0.3 of package base: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.

Changed in version 8.1.0.3 of package base: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.

Changed in version 8.1.0.3 of package base: Added the #:permissions argument.
Changed in version 8.7.0.10: Added the #:replace-permissions? argument.

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 on Windows and advisory on other platforms. Multiple tries for a 'shared lock on a single port can succeed; on Unix and Mac OS, a single port-file-unlock release the lock, while on other Windows, a port-file-unlock is needed for each successful port-try-file-lock?. On Unix and Mac OS, multiple tries for a 'exclusive lock can succeed and a single port-file-unlock releases the lock, while on Windows, a try for an 'exclusive lock fails for a given port if the port already holds the lock.

A lock acquired for an input port from open-input-output-file can be released through port-file-unlock on the corresponding output port, and vice versa. If the output port from open-input-output-file holds an 'exclusive lock, the corresponding input port can still acquire a 'shared lock, even multiple times; on Windows, a port-file-unlock is needed for each successful lock try, while a single port-file-unlock balances the lock tries on Unix and Mac OS. A 'shared lock on an input port can be upgraded to an 'exclusive lock through the corresponding output port on Unix and Mac OS, in which case a single port-file-unlock (on either port) releases the lock, while such upgrades are not allowed on Windows.

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