File Manipulation - MIT/GNU Scheme 7.7.90+
Description: MIT/GNU Scheme 7.7.90+

Next: Directory Reader, Previous: Working Directory, Up: Operating-System Interface

### 15.3 File Manipulation

This section describes procedures that manipulate files and directories. Any of these procedures can signal a number of errors for many reasons. The specifics of these errors are much too operating-system dependent to document here. However, if such an error is signalled by one of these procedures, it will be of type `condition-type:file-operation-error`.

— procedure: file-exists? filename
— procedure: file-exists-direct? filename
— procedure: file-exists-indirect? filename

> These procedures return `#t` if filename is an existing file or directory; otherwise they return `#f`. In operating systems that support symbolic links, if the file is a symbolic link, `file-exists-direct?` tests for the existence of the link, while `file-exists-indirect?` and `file-exists?` test for the existence of the file pointed to by the link.

— procedure: copy-file source-filename target-filename

> Makes a copy of the file named by source-filename. The copy is performed by creating a new file called target-filename, and filling it with the same data as source-filename.

— procedure: rename-file source-filename target-filename

> Changes the name of source-filename to be target-filename. In the unix implementation, this will not rename across file systems.

— procedure: delete-file filename

> Deletes the file named filename.

— procedure: delete-file-no-errors filename

> Like `delete-file`, but returns a boolean value indicating whether an error occurred during the deletion. If no errors occurred, `#t` is returned. If an error of type `condition-type:file-error` or `condition-type:port-error` is signalled, `#f` is returned.

— procedure: hard-link-file source-filename target-filename

> Makes a hard link from source-filename to target-filename. This operation gives the file specified by source-filename a new name, in addition to the old name.

> This currently works only on unix systems. It is further restricted to work only when source-filename and target-filename refer to names in the same file system.

— procedure: soft-link-file source-filename target-filename

> Creates a new soft link called target-filename that points at the file source-filename. (Soft links are also sometimes called symbolic links.) Note that source-filename will be interpreted as a string (although you may specify it as a pathname object, if you wish). The contents of this string will be stored in the file system as the soft link. When a file operation attempts to open the link, the contents of the link are interpreted relative to the link's location at that time.

> This currently works only on unix systems.

— procedure: make-directory filename

> Creates a new directory named filename. Signals an error if filename already exists, or if the directory cannot be created.

— procedure: delete-directory filename

> Deletes the directory named filename. Signals an error if the directory does not exist, is not a directory, or contains any files or subdirectories.

— procedure: ->truename filename

> This procedure attempts to discover and return the “true name” of the file associated with filename within the file system. An error of type `condition-type:file-operation-error` is signalled if the appropriate file cannot be located within the file system.

— procedure: call-with-temporary-file-pathname procedure

> Calls `temporary-file-pathname` to create a temporary file, then calls procedure with one argument, the pathname referring to that file. When procedure returns, if the temporary file still exists, it is deleted; then, the value yielded by procedure is returned. If procedure escapes from its continuation, and the file still exists, it is deleted.

— procedure: temporary-file-pathname [directory]

> Creates a new empty temporary file and returns a pathname referring to it. The temporary file is created with Scheme's default permissions, so barring unusual circumstances it can be opened for input and/or output without error. The temporary file will remain in existence until explicitly deleted. If the file still exists when the Scheme process terminates, it will be deleted.

> If directory is specified, the temporary file will be stored there. If it is not specified, or if it is `#f`, the temporary file will be stored in the directory returned by `temporary-directory-pathname`.

— procedure: temporary-directory-pathname

> Returns the pathname of an existing directory that can be used to store temporary files. These directory names are tried, in order, until a writeable directory is found:

> - The directories specified by the environment variables `TMPDIR`, `TEMP`, or `TMP`.
> - Under unix, the directories /var/tmp, /usr/tmp, or /tmp.
> - Under OS/2 or Windows, the following directories on the system drive: \temp, \tmp, or \.
> - Under OS/2 or Windows, the current directory, as specified by `*default-pathname-defaults*`.

— procedure: file-directory? filename

> Returns `#t` if the file named filename exists and is a directory. Otherwise returns `#f`. In operating systems that support symbolic links, if filename names a symbolic link, this examines the file linked to, not the link itself.

> This is equivalent to

>               (eq? 'directory (file-type-indirect filename))

— procedure: file-regular? filename

> Returns `#t` if the file named filename exists and is a regular file (i.e. not a directory, symbolic link, device file, etc.). Otherwise returns `#f`. In operating systems that support symbolic links, if filename names a symbolic link, this examines the file linked to, not the link itself.

> This is equivalent to

>               (eq? 'regular (file-type-indirect filename))

— procedure: file-symbolic-link? filename

> In operating systems that support symbolic links, if the file named filename exists and is a symbolic link, this procedure returns the contents of the symbolic link as a newly allocated string. The returned value is the name of the file that the symbolic link points to and must be interpreted relative to the directory of filename. If filename either does not exist or is not a symbolic link, or if the operating system does not support symbolic links, this procedure returns `#f`.

— procedure: file-type-direct filename
— procedure: file-type-indirect filename

> If the file named filename exists, `file-type-direct` returns a symbol specifying what type of file it is. For example, if filename refers to a directory, the symbol `directory` is returned. If filename doesn't refer to an existing file, `#f` is returned.

> If filename refers to a symbolic link, `file-type-direct` returns the type of the link itself, while `file-type-indirect` returns the type of the file linked to.

> At this time, the symbols that can be returned are the following. The names are intended to be self-explanatory. Most of these names can only be returned on particular operating systems, and so the operating-system name is prefixed to the name.

>               regular
>               directory
>               unix-symbolic-link
>               unix-character-device
>               unix-block-device
>               unix-named-pipe
>               unix-socket
>               os2-named-pipe
>               win32-named-pipe

— procedure: file-readable? filename

> Returns `#t` if filename names a file that can be opened for input; i.e. a readable file. Otherwise returns `#f`.

— procedure: file-writeable? filename

> Returns `#t` if filename names a file that can be opened for output; i.e. a writeable file. Otherwise returns `#f`.

— procedure: file-executable? filename

> Returns `#t` if filename names a file that can be executed. Otherwise returns `#f`. Under unix, an executable file is identified by its mode bits. Under OS/2, an executable file has one of the file extensions .exe, .com, .cmd, or .bat. Under Windows, an executable file has one of the file extensions .exe, .com, or .bat.

— procedure: file-access filename mode

> Mode must be an exact integer between `0` and `7` inclusive; it is a bitwise-encoded predicate selector with `1` meaning “executable”, `2` meaning “writeable”, and `4` meaning “readable”. `file-access` returns `#t` if filename exists and satisfies the predicates selected by mode. For example, if mode is `5`, then filename must be both readable and executable. If filename doesn't exist, or if it does not satisfy the selected predicates, `#f` is returned.

— procedure: file-eq? filename1 filename2

> Determines whether filename1 and filename2 refer to the same file. Under unix, this is done by comparing the inodes and devices of the two files. Under OS/2 and Windows, this is done by comparing the filename strings.

— procedure: file-modes filename

> If filename names an existing file, `file-modes` returns an exact non-negative integer encoding the file's permissions. The encoding of this integer is operating-system dependent. Under unix, it is the least-significant 12 bits of the `st_mode` element of the `struct stat` structure. Under OS/2 and Windows, it is the file attribute bits, which are described below. If filename does not name an existing file, `#f` is returned.

— procedure: set-file-modes! filename modes

> Filename must name an existing file. Modes must be an exact non-negative integer that could have been returned by a call to `file-modes`. `set-file-modes!` modifies the file's permissions to be those encoded by modes.

— variable: os2-file-mode/read-only
— variable: os2-file-mode/hidden
— variable: os2-file-mode/system
— variable: os2-file-mode/directory
— variable: os2-file-mode/archived

> The values of these variables are the “mode bits” that comprise the value returned by `file-modes` under OS/2. These bits are small integers that are combined by adding to form a complete set of modes. The integer zero represents a set of modes in which none of these bits are set.

— variable: nt-file-mode/read-only
— variable: nt-file-mode/hidden
— variable: nt-file-mode/system
— variable: nt-file-mode/directory
— variable: nt-file-mode/archive
— variable: nt-file-mode/normal
— variable: nt-file-mode/temporary
— variable: nt-file-mode/compressed

> The values of these variables are the “mode bits” that comprise the value returned by `file-modes` under Windows. These bits are small integers that are combined by adding to form a complete set of modes. The integer zero represents a set of modes in which none of these bits are set.

— procedure: file-modification-time filename

> Returns the modification time of filename as an exact non-negative integer. The result may be compared to other file times using ordinary integer arithmetic. If filename names a file that does not exist, `file-modification-time` returns `#f`.

> In operating systems that support symbolic links, if filename names a symbolic link, `file-modification-time` returns the modification time of the file linked to. An alternate procedure, `file-modification-time-direct`, returns the modification time of the link itself; in all other respects it is identical to `file-modification-time`. For symmetry, `file-modification-time-indirect` is a synonym of `file-modification-time`.

— procedure: file-access-time filename

> Returns the access time of filename as an exact non-negative integer. The result may be compared to other file times using ordinary integer arithmetic. If filename names a file that does not exist, `file-access-time` returns `#f`.

> In operating systems that support symbolic links, if filename names a symbolic link, `file-access-time` returns the access time of the file linked to. An alternate procedure, `file-access-time-direct`, returns the access time of the link itself; in all other respects it is identical to `file-access-time`. For symmetry, `file-access-time-indirect` is a synonym of `file-access-time`.

— procedure: set-file-times! filename access-time modification-time

> Filename must name an existing file, while access-time and modification-time must be valid file times that might have been returned by `file-access-time` and `file-modification-time`, respectively. `set-file-times!` alters the access and modification times of the file specified by filename to the values given by access-time and modification-time, respectively. For convenience, either of the time arguments may be specified as `#f`; in this case the corresponding time is not changed. `set-file-times!` returns an unspecified value.

— procedure: current-file-time

> Returns the current time as an exact non-negative integer, in the same format used by the above file-time procedures. This number can be compared to other file times using ordinary arithmetic operations.

— procedure: file-touch filename

> Touches the file named filename. If the file already exists, its modification time is set to the current file time and `#f` is returned. Otherwise, the file is created and `#t` is returned. This is an atomic test-and-set operation, so it is useful as a synchronization mechanism.

— procedure: file-length filename

> Returns the length, in bytes, of the file named filename as an exact non-negative integer.

— procedure: file-attributes filename

> This procedure determines if the file named filename exists, and returns information about it if so; if the file does not exist, it returns `#f`.

> In operating systems that support symbolic links, if filename names a symbolic link, `file-attributes` returns the attributes of the link itself. An alternate procedure, `file-attributes-indirect`, returns the attributes of the file linked to; in all other respects it is identical to `file-attributes`. For symmetry, `file-attributes-direct` is a synonym of `file-attributes`.

The information returned by `file-attributes` is decoded by accessor procedures. The following accessors are defined in all operating systems:

— procedure: file-attributes/type attributes

> The file type: `#t` if the file is a directory, a character string (the name linked to) if a symbolic link, or `#f` for all other types of file.

— procedure: file-attributes/access-time attributes

> The last access time of the file, an exact non-negative integer.

— procedure: file-attributes/modification-time attributes

> The last modification time of the file, an exact non-negative integer.

— procedure: file-attributes/change-time attributes

> The last change time of the file, an exact non-negative integer.

— procedure: file-attributes/length attributes

> The length of the file in bytes.

— procedure: file-attributes/mode-string attributes

> The mode string of the file, a newly allocated string showing the file's mode bits. Under unix, this string is in unix format. Under OS/2 and Windows, this string shows the standard “DOS” attributes in their usual format.

— procedure: file-attributes/n-links attributes

> The number of links to the file, an exact positive integer. Under Windows and OS/2, this is always `1`.

The following additional accessors are defined under unix:

— procedure: file-attributes/uid attributes

> The user id of the file's owner, an exact non-negative integer.

— procedure: file-attributes/gid attributes

> The group id of the file's group, an exact non-negative integer.

— procedure: file-attributes/inode-number attributes

> The inode number of the file, an exact non-negative integer.

The following additional accessor is defined under OS/2 and Windows:

— procedure: file-attributes/modes attributes

> The attribute bits of the file. This is an exact non-negative integer containing the file's attribute bits, exactly as specified by the operating system's API.

The following additional accessor is defined under OS/2:

— procedure: file-attributes/allocated-length attributes

> The allocated length of the file, which can be larger than the length of the file due to fixed-length allocation units.