Next: Directory Reader, Previous: Working Directory, Up: Operating-System Interface [Contents][Index]
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.
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.
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.
Changes the name of source-filename to be target-filename. In the unix implementation, this will not rename across file systems.
Deletes the file named 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.
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.
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.
Creates a new directory named filename. Signals an error if filename already exists, or if the directory cannot be created.
Deletes the directory named filename. Signals an error if the directory does not exist, is not a directory, or contains any files or subdirectories.
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.
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.
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.
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:
TMPDIR,
TEMP, or TMP.
param:default-pathname-defaults.
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))
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))
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.
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
Returns #t if filename names a file that can be opened for
input; i.e. a readable file. Otherwise returns #f.
Returns #t if filename names a file that can be opened for
output; i.e. a writeable file. Otherwise returns #f.
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 Windows, an executable file has
one of the file extensions .exe, .com, or .bat.
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.
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 Windows, this is done by comparing the filename strings.
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 Windows, it is the file
attribute bits, which are described below. If filename does not
name an existing file, #f is returned.
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.
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.
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.
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.
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.
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.
Returns the length, in bytes, of the file named filename as an exact non-negative integer.
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:
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.
The last access time of the file, an exact non-negative integer.
The last modification time of the file, an exact non-negative integer.
The last change time of the file, an exact non-negative integer.
The length of the file in bytes.
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 Windows, this string shows the standard “DOS” attributes in their usual format.
The number of links to the file, an exact positive integer. Under
Windows, this is always 1.
The following additional accessors are defined under unix:
The user id of the file’s owner, an exact non-negative integer.
The group id of the file’s group, an exact non-negative integer.
The inode number of the file, an exact non-negative integer.
The following additional accessor is defined under Windows:
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.
Next: Directory Reader, Previous: Working Directory, Up: Operating-System Interface [Contents][Index]