Go to the previous, next section.
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:
TEMP
environment variable, if any.
TMP
environment variable, if any.
*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.
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.
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.