The file-system Module

Introduction

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.

This chapter describes the functions and types that the File-System module contains.

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:
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 and rename-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:
Values:
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:
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:
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:
Values:
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:
Values:
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:
Values:
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" <integer>
#"creation-date" <date>
#"access-date" <date>
#"modification-date" <date>
#"readable?" <boolean>
#"writeable?" <boolean>
#"executable?" <boolean>

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" <integer>
#"creation-date" <date>
#"access-date" <date>
#"modification-date" <date>
#"readable?" <boolean>
#"writeable?" <boolean>
#"executable?" <boolean>

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:<error>, <simple-condition>
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:
Values:
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:
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:
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:
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 the TMP 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 of working-directory in conjunction with concatenate 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:
Values:
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: