The file-system Module¶
The File-System module is part of the System library and provides a generic interface to the file system of the local machine. Remotely mounted file systems are also accessible using this module.
Contents
Types specific to file system operations¶
The File-System module contains a number of types specifically designed for use by interfaces in the module.
Manipulating files¶
The File-System module contains a number of interfaces that let you perform standard file management operations on files already resident on the filesystem. You can rename, copy, or delete any file, and you can set any available properties for the file.
Manipulating directories¶
The File-System module contains a number of interfaces that let you create and delete directories. These can be used in conjunction with the file manipulation operations described in Manipulating files to perform file management tasks at any position in the file system.
Finding out file system information¶
A number of functions return environment information regarding the directory structure of the file system. Each function takes no arguments, and returns a pathname or list of pathnames. The return values can be use in conjunction with other functions to perform file-based operations relative to the directories involved.
Finding out file information¶
Several interfaces in the File-System module allow you to interrogate files for information. You can find out whether a file exists, what its name is, or which directory it resides in, and you can find the current properties of the file.
The FILE-SYSTEM module¶
This section contains a reference entry for each item included in the File-System module.
-
copy-file
Function¶ Creates a copy of a file.
- Signature
copy-file old-file new-file #key if-exists => ()
- Parameters
old-file – An instance of
<pathname>
.new-file – An instance of
<pathname>
.if-exists (#key) – An instance of
<copy/rename-disposition>
. Default value:#"signal"
.
- Discussion
Copies old-file to new-file. If new-file already exists, the action of this function is controlled by the value of if-exists. The default is to prompt you before overwriting an existing file.
- See also
-
<copy/rename-disposition>
Type¶ The type that represents possible actions when overwriting existing files.
- Equivalent
one-of(#"signal", #"replace")
- Discussion
This type represents the acceptable values for the if-exists: argument to the
copy-file
andrename-file
functions. Only two values are acceptable:If
#"signal"
is used, then you are warned before a file is overwritten during a copy or move operation.If
#"replace"
is used, then you are not warned before a file is overwritten during a copy or move operation.
- Operations
- See also
-
create-directory
Function¶ Creates a new directory in the specified parent directory.
- Signature
create-directory parent name => directory
- Parameters
parent – An instance of
<pathname>
.name – An instance of
<string>
.
- Values
directory – An instance of
<pathname>
.
- Discussion
Creates directory in the specified parent directory. The return value of this function can be used with
concatenate
to create pathnames of entities in the new directory.- See also
-
delete-directory
Function¶ Deletes the specified directory.
- Signature
delete-directory directory #key recursive? => ()
- Parameters
directory – An instance of
<pathname>
.recursive? (#key) – An instance of
<boolean>
. Default value:#f
- Discussion
Deletes the specified directory. By default the directory may only be deleted if it is empty. Pass
recursive?: #t
to delete the directory and its contents recursively.- See also
-
delete-file
Function¶ Deletes the specified file system entity.
- Signature
delete-file file => ()
- Parameters
file – An instance of
<pathname>
.
- Discussion
Deletes the file system entity specified by file. If file refers to a link, the link is removed, but the actual file that the link points to is not removed.
-
do-directory
Function¶ Executes the supplied function once for each entity in the specified directory.
- Signature
do-directory function directory => ()
- Parameters
function – An instance of
<function>
.directory – An instance of
<pathname>
.
- Discussion
Executes function once for each entity in directory.
The signature of function is:
*function* *directory* *name* *type* => ()
where directory is an instance of
<pathname>
, name is an instance of<byte-string>
, and type is an instance of<file-type>
.Within function, the values of directory and name can be concatenated to generate a
<pathname>
suitable for use by the other functions in the module.The following calls are equivalent:
do-directory(my-function, "C:\\USERS\\JOHN\\FOO.TEXT") do-directory(my-function, "C:\\USERS\\JOHN\\")
as they both operate on the contents of
C:\\USERS\\JOHN
. The call:do-directory(my-function, "C:\\USERS\\JOHN")
is not equivalent as it will operate on the contents of
C:\\USERS
.
-
ensure-directories-exist
Function¶ Ensures that all the directories in the pathname leading to a file exist, creating any that do not, as needed.
- Signature
ensure-directories-exist file => created?
- Parameters
file – An instance of
<pathname>
.
- Values
created? – An instance of
<boolean>
.
- Discussion
Ensures that all the directories in the pathname leading to a file exist, creating any that do not, as needed. The return value indicates whether or not any directory was created.
The following calls are equivalent:
ensure-directories-exist("C:\\USERS\\JOHN\\FOO.TEXT") ensure-directories-exist("C:\\USERS\\JOHN\\")
as they will both create the directories USERS and JOHN if needed. The call:
ensure-directories-exist("C:\\USERS\\JOHN")
is not equivalent as it will only create USERS if needed.
- Example
ensure-directories-exist("C:\\USERS\\JOHN\\FOO.TEXT")
- See also
-
file-exists?
Function¶ Returns
#t
if the specified file exists.- Signature
file-exists? file => exists?
- Parameters
file – An instance of
<pathname>
.
- Values
exists? – An instance of
<boolean>
.
- Discussion
Returns
#t
if file exists. If it refers to a link, the target of the link is checked.
-
file-properties
Function¶ Returns all the properties of a file system entity.
- Signature
file-properties file => properties
- Parameters
file – An instance of
<pathname>
.
- Values
properties – An instance of a concrete subclass of
<explicit-key-collection>
.
- Discussion
Returns all the properties of file. The keys to the properties collection are the same as those use by
file-property
, above.- Example
file-properties() [#"size"]
- See also
-
file-property
Sealed Generic function¶ Returns the specified property of a file system entity.
- Signature
file-property file #key key => property
- Parameters
file – An instance of
<pathname>
.key (#key) – One of
#"author"
,#"size"
,#"creation-date"
,#"access-date"
,#"modification-date"
,#"readable?"
,#"writeable?"
,#"executable?"
.
- Values
property – The value of the property specified by key. The type of the value returned depends on the value of key: see the description for details.
- Discussion
Returns the property of file specified by key. The value returned depends on the value of key, as shown in Table Return value types of file-property.
Return value types of file-property
¶Value of key
Type of return value
#"author"
false-or(<string>)
#"size"
#"creation-date"
#"access-date"
#"modification-date"
#"readable?"
#"writeable?"
#"executable?"
Not all platforms implement all of the above keys. Some platforms may support additional keys. The
#"author"
key is supported on all platforms but may return#f
if it is not meaningful on a given platform. Use of an unsupported key signals an error.All keys listed above are implemented by Win32, though note that
#"author"
always returns#f
.- See also
-
file-property-setter
Sealed Generic function¶ Sets the specified property of a file system entity to a given value.
- Signature
file-property-setter new-value file key => new-value
- Parameters
new-value – The type of this depends on the value of key. See the description for details.
file – An instance of
<pathname>
.key – One of
#"author"
,#"size"
,#"creation-date"
,#"access-date"
,#"modification-date"
,#"readable?"
,#"writeable?"
,#"executable?"
.
- Values
new-value – The type of this depends on the value of key. See the description for details.
- Discussion
Sets the property of file specified by key to new-value. The type of new-value depends on the property specified by key, as shown in Table New value types of file-property-setter below.
New value types of file-property-setter¶ Value of key
Type of new-value
#"author"
false-or(<string>)
#"size"
#"creation-date"
#"access-date"
#"modification-date"
#"readable?"
#"writeable?"
#"executable?"
Note that file-property-setter returns the value that was set, and so return values have the same types as specified values, depending on the value of key.
Not all platforms implement all of the above keys. Some platforms may support additional keys. Use of an unsupported key signals an error.
The only property that can be set on Win32 is
#"writeable?"
.- See also
-
<file-system-error>
Class¶ Error type signaled when any other functions in the File-System module signal an error.
- Superclasses
- Discussion
Signalled when one of the file system functions triggers an error, such as a permissions error when trying to delete or rename a file.
-
file-type
Function¶ Returns the type of the specified file system entity.
- Signature
file-type file => file-type
- Parameters
file – An instance of
<pathname>
.
- Values
file-type – An instance of
<file-type>
.
- Discussion
Returns the type of file, the specified file system entity. A file system entity can either be a file, a directory, or a link to another file or directory.
-
<file-type>
Type¶ The type representing all possible types of a file system entity.
- Equivalent
one-of(#"file", #"directory", #"link")
- Discussion
The type representing all possible types of a file system entity. An entity on the file system can either be a file, a directory or folder, or a link to another file or directory. The precise terminology used to refer to these different types of entity depends on the operating system you are working in.
- Operations
-
home-directory
Function¶ Returns the current value of the home directory.
- Signature
home-directory () => home-directory
- Values
home-directory – An instance of
<pathname>
.
- Discussion
Returns the current value of the home directory. The return value of this function can be used with concatenate to create pathnames of entities in the home directory.
-
<pathname>
Type¶ The type representing a file system entity.
- Equivalent
type-union(<string>, <file-system-locator>)
- Discussion
A type that identifies a file system entity. This can be either a
<string>
or a<file-system-locator>
.- Operations
-
rename-file
Function¶ Renames a specified file.
- Signature
rename-file old-file new-file #key if-exists => ()
- Parameters
old-file – An instance of
<pathname>
.new-file – An instance of
<pathname>
.if-exists – An instance of
<copy/rename-disposition>
. Default value:#"signal"
.
- Discussion
Renames old-file to new-file. If new-file already exists, the action of this function is controlled by the value of if-exists. The default is to prompt you before overwriting an existing file.
This operation may fail if the source and destination are not on the same file system.
- See also
-
root-directories
Function¶ Returns a sequence containing the pathnames of the root directories of the file systems on the local machine.
- Signature
root-directories () => roots
- Values
roots – An instance of
<sequence>
.
- Discussion
Returns a sequence containing the pathnames of the root directories of the file systems on the local machine.
-
temp-directory
Function¶ Returns the pathname of the temporary directory in use.
- Signature
temp-directory () => temp-directory
- Values
temp-directory – An instance of
<pathname>
, or false.
- Discussion
Returns the pathname of the temporary directory in use. The return value of this function can be used with
concatenate
to create pathnames of entities in the temporary directory. If no temporary directory is defined,temp-directory
returns#f
. On Windows the temporary directory is specified by theTMP
environment variable.
-
working-directory
Function¶ Returns the working directory for the current process.
- Signature
working-directory () => working-directory
- Values
working-directory – An instance of
<pathname>
.
- Discussion
Returns the
<pathname>
of the current working directory in the current process on the local machine. You can use the return value ofworking-directory
in conjunction withconcatenate
to specify pathnames of entities in the working directory.- See also
-
working-directory-setter
Function¶ Sets the working directory for the current process.
- Signature
working-directory-setter directory => directory
- Parameters
directory – An instance of
<pathname>
.
- Values
directory – An instance of
<pathname>
.
- Discussion
Sets the working directory for the current process.
Note that the following calls are equivalent
working-directory() := "C:\\USERS\\JOHN\\FOO.TEXT"; working-directory() := "C:\\USERS\\JOHN\\";
as they will both set the working directory to C:\USERS\JOHN. The call
working-directory() := "C:\\USERS\\JOHN";
is not equivalent as it sets the working directory to C:\USERS.
- Example
working-directory() := "C:\\USERS\\JOHN\\";
- See also