14.2 Filesystem
14.2.1 Locating Paths
(find-system-path kind) → path? |
kind : symbol? |
Returns a machine-specific path for a standard type of path specified by kind, which must be one of the following:
'home-dir – the current user’s home directory.
Under Unix and Mac OS X, this directory is determined by expanding the path "~", which is expanded by first checking for a HOME environment variable. If none is defined, the USER and LOGNAME environment variables are consulted (in that order) to find a user name, and then system files are consulted to locate the user’s home directory.
Under Windows, the user’s home directory is the user-specific profile directory as determined by the Windows registry. If the registry cannot provide a directory for some reason, the value of the USERPROFILE environment variable is used instead, as long as it refers to a directory that exists. If USERPROFILE also fails, the directory is the one specified by the HOMEDRIVE and HOMEPATH environment variables. If those environment variables are not defined, or if the indicated directory still does not exist, the directory containing the current executable is used as the home directory.
'pref-dir – the standard directory for storing the current user’s preferences. Under Unix, the directory is ".plt-scheme" in the user’s home directory. Under Windows, it is "PLT Scheme" in the user’s application-data folder as specified by the Windows registry; the application-data folder is usually "Application Data" in the user’s profile directory. Under Mac OS X, it is "Library/Preferences" in the user’s home directory. This directory might not exist.
'pref-file – a file that contains a symbol-keyed association list of preference values. The file’s directory path always matches the result returned for 'pref-dir. The file name is "plt-prefs.ss" under Unix and Windows, and it is "org.plt-scheme.prefs.ss" under Mac OS X. The file’s directory might not exist. See also get-preference.
'temp-dir – the standard directory for storing temporary files. Under Unix and Mac OS X, this is the directory specified by the TMPDIR environment variable, if it is defined, otherwise it is the first path that exists among "/var/tmp", "/usr/tmp", and "/tmp". Under Windows, the result is the directory specified by the TMP or TEMP environment variable, if it is defined, otherwise it is the current directory.
'init-dir – the directory containing the initialization file used by stand-alone mzscheme executable. It is the same as the current user’s home directory.
'init-file – the file loaded at start-up by the stand-alone mzscheme executable. The directory part of the path is the same path as returned for 'init-dir. The file name is platform-specific:
'addon-dir – a directory for installing PLT Scheme extensions. It’s the same as 'pref-dir, except under Mac OS X, where it is "Library/PLT Scheme" in the user’s home directory. This directory might not exist.
'doc-dir – the standard directory for storing the current user’s documents. Under Unix, it’s the same as 'home-dir. Under Mac OS X, it’s the "Documents" directory in the user’s home directory. Under Windows, it is the user’s documents folder as specified by the Windows registry; the documents folder is usually "My Documents" in the user’s home directory.
'desk-dir – the directory for the current user’s desktop. Under Unix, it’s the same as 'home-dir. Under Windows, it is the user’s desktop folder as specified by the Windows registry; the documents folder is usually "Desktop" in the user’s home directory. Under Mac OS X, it is the desktop directory, which is specifically "~/Desktop" under Mac OS X.
'sys-dir – the directory containing the operating system for Windows. Under Unix and Mac OS X, the result is "/".
'exec-file – the path of the mzscheme executable as provided by the operating system for the current invocation.
For MrEd, the executable path is the name of a MrEd executable.
'run-file – the path of the current executable; this may be different from result for 'exec-file because an alternate path was provided through a --name or -N command-line flag to the mzscheme (or mred) executable, or because an embedding executable installed an alternate path. In particular a “launcher” script created by make-mzscheme-launcher sets this path to the script’s path. In the mzscheme executable, this path is also bound initially to program.
'collects-dir – a path to the main collection of libraries (see Libraries and Collections). If this path is relative, then it is relative to the executable as reported by (find-system-path 'exec-file) – though the latter could be a soft-link or relative to the user’s executable search path, so that the two results should be combined with find-executable-path. The 'collects-dir path is normally embedded in the mzscheme executable, but it can be overridden by the --collects or -X command-line flag.
'orig-dir – the current directory at start-up, which can be useful in converting a relative-path result from (find-system-path 'exec-file) or (find-system-path 'run-file) to a complete path.
| ||||||||
Parses a string or byte string containing a list of paths, and returns a list of path strings. Under Unix and Mac OS X, paths in a path list are separated by a :; under Windows, paths are separated by a ;. Whenever the path list contains an empty path, the list default-path-list is spliced into the returned list of paths. Parts of str that do not form a valid path are not included in the returned list.
| |||||||||||||||||||||
program-sub : path-string? | |||||||||||||||||||||
related-sub : path-string? | |||||||||||||||||||||
deepest? : any/c = #f |
Finds a path for the executable program-sub, returning #f if the path cannot be found.
If related-sub is not #f, then it must be a relative path string, and the path found for program-sub must be such that the file or directory related-sub exists in the same directory as the executable. The result is then the full path for the found related-sub, instead of the path for the executable.
This procedure is used by the mzscheme executable to find the standard library collection directory (see Libraries and Collections). In this case, program is the name used to start MzScheme and related is "collects". The related-sub argument is used because, under Unix and Mac OS X, program-sub may involve to a sequence of soft links; in this case, related-sub determines which link in the chain is relevant.
If related-sub is not #f, then when find-executable-path does not finds a program-sub that is a link to another file path, the search can continue with the destination of the link. Further links are inspected until related-sub is found or the end of the chain of links is reached. If deepest? is #f (the default), then the result corresponds to the first path in a chain of links for which related-sub is found (and further links are not actually explored); otherwise, the result corresponds to the last link in the chain for which related-sub is found.
If program-sub is a pathless name, find-executable-path gets the value of the PATH environment variable; if this environment variable is defined, find-executable-path tries each path in PATH as a prefix for program-sub using the search algorithm described above for path-containing program-subs. If the PATH environment variable is not defined, program-sub is prefixed with the current directory and used in the search algorithm above. (Under Windows, the current directory is always implicitly the first item in PATH, so find-executable-path checks the current directory first under Windows.)
14.2.2 Files
(file-exists? path) → boolean? |
path : path-string? |
Returns #t if a file (not a directory) path exists, #f otherwise.
Under Windows, file-exists? reports #t for all variations of the special filenames (e.g., "LPT1", "x:/baddir/LPT1").
(link-exists? path) → boolean? |
path : path-string? |
Returns #t if a link path exists (Unix and Mac OS X), #f otherwise.
The predicates file-exists? or directory-exists? work on the final destination of a link or series of links, while link-exists? only follows links to resolve the base part of path (i.e., everything except the last name in the path).
This procedure never raises the exn:fail:filesystem exception.
(delete-file path) → void? |
path : path-string? |
Feletes the file with path path if it exists, otherwise the exn:fail:filesystem exception is raised. If path is a link, the link is deleted rather than the destination of the link.
| |||||||||||||||||||||
old : path-string? | |||||||||||||||||||||
new : path-string? | |||||||||||||||||||||
exists-ok? : any/c = #f |
Renames the file or directory with path old – if it exists – to the path new. If the file or directory is not renamed successfully, the exn:fail:filesystem exception is raised.
This procedure can be used to move a file/directory to a different directory (on the same disk) as well as rename a file/directory within a directory. Unless exists-ok? is provided as a true value, new cannot refer to an existing file or directory. Even if exists-ok? is true, new cannot refer to an existing file when old is a directory, and vice versa. (If new exists and is replaced, the replacement is atomic in the filesystem, except under Windows 95, 98, or Me. However, the check for existence is not included in the atomic action, which means that race conditions are possible when exists-ok? is false or not supplied.)
If old is a link, the link is renamed rather than the destination of the link, and it counts as a file for replacing any existing new.
| |||||||||||||||||||||
path : path-string? | |||||||||||||||||||||
secs-n : (or/c exact-integer? false/c) = #f | |||||||||||||||||||||
|
Returns the file or directory’s last modification date as platform-specific seconds (see also Time) when secs-n is not provided or is #f. (For FAT filesystems under Windows, directories do not have modification dates. Therefore, the creation date is returned for a directory, but the modification date is returned for a file.)
If secs-n is provided and not #f, the access and modification times of path are set to the given time.
On error (e.g., if no such file exists), fail-thunk is called, and the default fail-thunk raises exn:fail:filesystem.
(file-or-directory-permissions path) → (listof symbol?) |
path : path-string? |
Returns a list containing 'read, 'write, and/or 'execute for the given file or directory path. On error (e.g., if no such file exists), the exn:fail:filesystem exception is raised. Under Unix and Mac OS X, permissions are checked for the current effective user instead of the real user.
(file-size path) → nonnegative-exact-integer? |
path : path-string? |
Returns the (logical) size of the specified file in bytes. Under Mac OS X, this size excludes the resource-fork size. On error (e.g., if no such file exists), the exn:fail:filesystem exception is raised.
src : path-string? |
dest : path-string? |
Creates the file dest as a copy of src. If the file is not successfully copied, the exn:fail:filesystem exception is raised. If dest already exists, the copy will fail. File permissions are preserved in the copy. Under Mac OS X, the resource fork is also preserved in the copy. If src refers to a link, the target of the link is copied, rather than the link itself.
(make-file-or-directory-link to path) → void? |
to : path-string? |
path : path-string? |
Creates a link path to to under Unix and Mac OS X. The creation will fail if path already exists. The to need not refer to an existing file or directory, and to is not expanded before writing the link. If the link is not created successfully,the exn:fail:filesystem exception is raised. Under Windows, the exn:fail:unsupported exception is raised always.
14.2.3 Directories
See also: rename-file-or-directory, file-or-directory-modify-seconds, file-or-directory-permissions.
(current-directory path) → void? |
path : path-string? |
A parameter that determines the current directory for resolving relative paths.
When the parameter procedure is called to set the current directory, the path argument is cleansed using cleanse-path, simplified using simplify-path, and then converted to a directory path with path->directory-path; cleansing and simplification raise an exception if the path is ill-formed. Thus, the current value of current-directory is always a cleansed, simplified, complete, directory path.
The path is not checked for existence when the parameter is set.
(current-drive) → path? |
Returns the current drive name Windows. For other platforms, the exn:fail:unsupported exception is raised. The current drive is always the drive of the current directory.
(directory-exists? path) → boolean? |
path : path-string? |
Returns #t if path refers to a directory, #f otherwise.
(make-directory path) → void? |
path : path-string? |
Creates a new directory with the path path. If the directory is not created successfully, the exn:fail:filesystem exception is raised.
(delete-directory path) → void? |
path : path-string? |
Deletes an existing directory with the path path. If the directory is not deleted successfully, the exn:fail:filesystem exception is raised.
(directory-list [path]) → (listof path?) |
path : path-string? = (current-directory) |
Returns a list of all files and directories in the directory specified by path. If path is omitted, a list of files and directories in the current directory is returned. Under Unix and Mac OS X, an element of the list can start with ./~ if it would otherwise start with ~. Under Windows, an element of the list may start with \\?\REL\\.
(filesystem-root-list) → (listof path?) |
Returns a list of all current root directories. Obtaining this list can be particularly slow under Windows.
14.2.4 Declaring Paths Needed at Run Time
The bindings documented in this section are provided by the scheme/runtime-path library, not scheme/base or scheme.
The scheme/runtime-path library provides forms for accessing files and directories at run time using a path that are usually relative to an enclosing source file. Unlike using collection-path, define-runtime-path exposes each run-time path to tools like the executable and distribution creators, so that files and directories needed at run time are carried along in a distribution.
In addition to the bindings described below, scheme/runtime-path provides #%datum in phase level 1, since string constants are often used as compile-time expression with define-runtime-path.
(define-runtime-path id expr) |
Uses expr as both a compile-time (i.e., phase 1) expression and a run-time (i.e., phase 0) expression. In either context, expr should produce a path, a string that represents a path, a list of the form (list 'lib str ), or a list of the form (list 'so str).
For run time, id is bound to a path that is based on the result of expr. The path is normally computed by taking a relative path result from expr and adding it to a path for the enclosing file (which is computed as described below). However, tools like the executable creator can also arrange (by colluding with scheme/runtime-path) to have a different base path substituted in a generated executable. If expr produces an absolute path, it is normally returned directly, but again may be replaced by an executable creator. In all cases, the executable creator preserves the relative locations of all paths. When expr produces a relative or absolute path, then the path bound to id is always an absolute path.
If expr produces a list of the form (list 'lib str ), the value bound to id is an absolute path. The path refers to a collection-based file similar to using the value as a module path.
If expr produces a list of the form (list 'so str), the value bound to id can be either str or an absolute path; it is an absolute path when adding the platform-specific shared-library extension – as produced by (system-type 'so-suffix) – and then searching in the PLT-specific shared-object library directories (as determined by find-dll-dirs) locates the path. In this way, shared-object libraries that are installed specifically for PLT Scheme get carried along in distributions.
For compile-time, the expr result is used by an executable creator – but not the result when the containing module is compiled. Instead, expr is preserved in the module as a compile-time expression (in the sense of begin-for-syntax). Later, at the time that an executable is created, the compile-time portion of the module is executed (again), and the result of expr is the file to be included with the executable. The reason for the extra compile-time execution is that the result of expr might be platform-dependent, so the result should not be stored in the (platform-independent) bytecode form of the module; the platform at executable-creation time, however, is the same as at run time for the executable. Note that expr is still evaluated at run-time; consequently, avoid procedures like collection-path, which depends on the source installation, and instead use relative paths and forms like (list 'lib str ).
If a path is needed only on some platforms and not on others, use define-runtime-path-list with an expr that produces an empty list on platforms where the path is not needed.
The enclosing path for a define-runtime-path is determined as follows from the define-runtime-path syntactic form:
If the form has a source module according to syntax-source-module, then the source location is determined by preserving the original expression as a syntax object, extracting its source module path at run time (again using syntax-source-module), and then resolving the resulting module path index.
If the expression has no source module, the syntax-source location associated with the form is used, if is a string or path.
If no source module is available, and syntax-source produces no path, then current-load-relative-directory is used if it is not #f. Finally, current-directory is used if all else fails.
In the latter two cases, the path is normally preserved in (platform-specific) byte form. If it is is within the result of find-collects-dir, however, it the path is recorded relative to (find-collects-dir), and it is reconstructed using (find-collects-dir) at run time.
Examples:
; Access a file "data.txt" at run-time that is originally |
; located in the same directory as the module source file: |
(define-runtime-path data-file "data.txt") |
(define (read-data) |
(with-input-from-file data-file |
(lambda () |
(read-bytes (file-size data-file))))) |
|
; Load a platform-specific shared object (using ffi-lib) |
; that is located in a platform-specific sub-directory of the |
; module's source directory: |
(define-runtime-path libfit-path |
(build-path "compiled" "native" (system-library-subpath #f) |
(path-replace-suffix "libfit" |
(system-type 'so-suffix)))) |
(define libfit (ffi-lib libfit-path)) |
|
; Load a platform-specific shared object that might be installed |
; as part of the operating system, or might be installed |
; specifically for PLT Scheme: |
(define-runtime-path libssl-so |
(case (system-type) |
[(windows) '(so "ssleay32")] |
[else '(so "libssl")])) |
(define libssl (ffi-lib libssl-so)) |
(define-runtime-paths (id ) expr) |
Like define-runtime-path, but declares and binds multiple paths at once. The expr should produce as many values as ids.
(define-runtime-path-list id expr) |
Like define-runtime-path, but expr should produce a list of paths.
(runtime-paths module-path) |
This form is mainly for use by tools such as executable builders. It expands to a quoted list containing the run-time paths declared by module-path, returning the compile-time results of the declaration exprs, except that paths are converted to byte strings. The enclosing module must require (directly or indirectly) the module specified by module-path, which is an unquoted module path.
14.2.5 More File and Directory Utilities
The bindings documented in this section are provided by the scheme/file and scheme libraries, but not scheme/base.
(copy-directory/files src dest) → void? |
src : path-string? |
dest : path-string? |
Copies the file or directory src to dest, raising exn:fail:filesystem if the file or directory cannot be copied, possibly because dest exists already. If src is a directory, the copy applies recursively to the directory’s content. If a source is a link, the target of the link is copied rather than the link itself.
(delete-directory/files path) → void? |
path : path-string? |
Deletes the file or directory specified by path, raising exn:fail:filesystem if the file or directory cannot be deleted. If path is a directory, then delete-directory/files is first applied to each file and directory in path before the directory is deleted.
(find-files predicate [start-path]) → (listof path?) |
start-path : (or/c path-string? false/c) = #f |
Traverses the filesystem starting at start-path and creates a list of all files and directories for which predicate returns true. If start-path is #f, then the traversal starts from (current-directory). In the resulting list, each directory precedes its content.
The predicate procedure is called with a single argument for each file or directory. If start-path is #f, the argument is a pathname string that is relative to the current directory. Otherwise, it is a path building on start-path. Consequently, supplying (current-directory) for start-path is different from supplying #f, because predicate receives complete paths in the former case and relative paths in the latter. Another difference is that predicate is not called for the current directory when start-path is #f.
The find-files traversal follows soft links. To avoid following links, use the more general fold-files procedure.
If start-path does not refer to an existing file or directory, then predicate will be called exactly once with start-path as the argument.
(pathlist-closure path-list) → (listof path?) |
path-list : (listof path-string?) |
Given a list of paths, either absolute or relative to the current directory, returns a list such that
if a nested path is given, all of its ancestors are also included in the result (but the same ancestor is not added twice);
if a path refers to directory, all of its descendants are also included in the result;
ancestor directories appear before their descendants in the result list.
| ||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||
init-val : any/c | ||||||||||||||||||||||||||||
start-path : (or/c path-string? false/c) = #f | ||||||||||||||||||||||||||||
follow-links? : any/c = #t |
Traverses the filesystem starting at start-path, calling proc on each discovered file, directory, and link. If start-path is #f, then the traversal starts from (current-directory).
The proc procedure is called with three arguments for each file, directory, or link:
If start-path is #f, the first argument is a pathname string that is relative to the current directory. Otherwise, the first argument is a pathname that starts with start-path. Consequently, supplying (current-directory) for start-path is different from supplying #f, because proc receives complete paths in the former case and relative paths in the latter. Another difference is that proc is not called for the current directory when start-path is #f.
The second argument is a symbol, either 'file, 'dir, or 'link. The second argument can be 'link when follow-links? is #f, in which case the filesystem traversal does not follow links. If follow-links? is #t, then proc will only get a 'link as a second argument when it encounters a dangling symbolic link (one that does not resolve to an existing file or directory).
The third argument is the accumulated result. For the first call to proc, the third argument is init-val. For the second call to proc (if any), the third argument is the result from the first call, and so on. The result of the last call to proc is the result of fold-files.
The proc argument is used in an analogous way to the procedure argument of foldl, where its result is used as the new accumulated result. There is an exception for the case of a directory (when the second argument is 'dir): in this case the procedure may return two values, the second indicating whether the recursive scan should include the given directory or not. If it returns a single value, the directory is scanned.
An error is signaled if the start-path is provided but no such path exists, or if paths disappear during the scan.
(make-directory* path) → void? |
path : path-string? |
Creates directory specified by path, creating intermediate directories as necessary.
| |||||||||||||||||||||
template : string? = "mztmp~a" | |||||||||||||||||||||
| |||||||||||||||||||||
directory : (or/c path-string? false/c) = #f |
Creates a new temporary file and returns a pathname string for the file. Instead of merely generating a fresh file name, the file is actually created; this prevents other threads or processes from picking the same temporary name.
The template argument must be a format string suitable for use with format and one additional string argument (where the string contains only digits). If the resulting string is a relative path, it is combined with the result of (find-system-path 'temp-dir), unless directory is provided and non-#f, in which case the file name generated from template is combined with directory to obtain a full path.
If copy-from-filename is provided as path, the temporary file is created as a copy of the named file (using copy-file). If copy-from-filename is #f, the temporary file is created as empty. If copy-from-filename is 'directory, then the temporary “file” is created as a directory.
When a temporary file is created, it is not opened for reading or writing when the pathname is returned. The client program calling make-temporary-file is expected to open the file with the desired access and flags (probably using the 'truncate flag; see open-output-file) and to delete it when it is no longer needed.
| ||||||||||||||||||||||||||||
name : symbol? | ||||||||||||||||||||||||||||
flush-mode : any/c = 'timestamp | ||||||||||||||||||||||||||||
Extracts a preference value from the file designated by (find-system-path 'pref-file), or by filename if it is provided and is not #f. In the former case, if the preference file doesn’t exist, get-preferences attempts to read a "plt-prefs.ss" file in the "defaults" collection, instead. If neither file exists, the preference set is empty.
The preference file should contain a symbol-keyed association list (written to the file with the default parameter settings). Keys starting with mzscheme:, mred:, and plt: in any letter case are reserved for use by PLT.
The result of get-preference is the value associated with name if it exists in the association list, or the result of calling failure-thunk otherwise.
Preference settings are cached (weakly) across calls to get-preference, using (path->complete-path filename) as a cache key. If flush-mode is provided as #f, the cache is used instead of the re-consulting the preferences file. If flush-mode is provided as 'timestamp (the default), then the cache is used only if the file has a timestamp that is the same as the last time the file was read. Otherwise, the file is re-consulted.
See also put-preferences. For a more elaborate preference system, see preferences:get.
| ||||||||||||||||||||||||||||
vals : list? | ||||||||||||||||||||||||||||
locked-proc : (path? . -> . any) = (lambda (p) (error ....)) | ||||||||||||||||||||||||||||
filename : (or/c false/c path-string?) = #f |
Installs a set of preference values and writes all current values to the preference file designated by (find-system-path 'pref-file), or filename if it is supplied and not #f.
The names argument supplies the preference names, and vals must have the same length as names. Each element of vals must be an instance of a built-in data type whose write output is readable (i.e., the print-unreadable parameter is set to #f while writing preferences).
Current preference values are read from the preference file before updating, and an update “lock” is held starting before the file read, and lasting until after the preferences file is updated. The lock is implemented by the existence of a file in the same directory as the preference file. If the directory of the preferences file does not already exist, it is created.
If the update lock is already held (i.e., the lock file exists), then locked is called with a single argument: the path of the lock file. The default locked reports an error; an alternative thunk might wait a while and try again, or give the user the choice to delete the lock file (in case a previous update attempt encountered disaster).
If filename is #f or not supplied, and the preference file does not already exist, then values read from the "defaults" collection (if any) are written for preferences that are not mentioned in names.