Next: Directory Reader, Previous: Working Directory, Up: Operating-System Interface
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, whilefile-exists-indirect?
andfile-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.
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 typecondition-type:file-error
orcondition-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 bytemporary-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
, orTMP
.- Under unix, the directories /var/tmp, /usr/tmp, or /tmp.
- Under Windows, the following directories on the system drive: \temp, \tmp, or \.
- Under Windows, the current directory, as specified by
*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 symboldirectory
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, whilefile-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 win32-named-pipe
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
and7
inclusive; it is a bitwise-encoded predicate selector with1
meaning “executable”,2
meaning “writeable”, and4
meaning “readable”.file-access
returns#t
if filename exists and satisfies the predicates selected by mode. For example, if mode is5
, 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 thest_mode
element of thestruct 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 tofile-modification-time
. For symmetry,file-modification-time-indirect
is a synonym offile-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 tofile-access-time
. For symmetry,file-access-time-indirect
is a synonym offile-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
andfile-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 tofile-attributes
. For symmetry,file-attributes-direct
is a synonym offile-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 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: