— 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.

— 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.

— 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.

— 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.

— 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.