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.

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