Go to the previous, next section.

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

Returns #t if filename is an existing file or directory; otherwise returns #f. In operating systems that support symbolic links, if the file is a symbolic link, this procedure tests the existence of the file linked to, not the link itself.

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. If target-filename exists prior to this procedure's invocation, it is deleted before the new output file is created.

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+: 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

call-with-temporary-file-pathname 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

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.

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 writable directory is found:

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.

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-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-writable? filename

Returns #t if filename names a file that can be opened for output; i.e. a writable 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 "writable", 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, but typically it contains bits that indicate what users and processes are allowed to read, write, or execute the file. 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.

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.

Some operating systems don't implement access times; in those systems file-access-time returns an unspecified value.

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.

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. This is a newly allocated string showing the file's mode bits. Under unix and Windows, this string is in unix format (simulated under Windows). Under OS/2, this string shows the standard OS/2 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 accessors are defined under OS/2:

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 OS/2 API.

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.

Go to the previous, next section.