14.3 Filesystem🔗ℹ

The result can be #'directory_link only on Windows, which distinguishes file and directory links.

If recur is #false, then the result includes only files, directories, and links immediately within path. If recur is true, then each directory within path is followed by its own recursive content in the result list. If follow_links true, the a recursive traversal continues into a link that refers to a directory, otherwise the link is not traversed for the result list; link cycles can cause filesystem.files to never return.

The keep and skip functions are applied to every path encountered during a traversal, and a path is omitted from the list when keep returns #false or skip returns a true value for the path. When recur is true, skipping a directory (or link that refers to a directory) means that it is not traversed, so the directory’s content is also skipped. If keep returns #false for a path, then skip is not applied to the path.

When exists_ok is #false, a check is needed before the move operation internally, and that combination is not atomic on Unix and Mac OS. If to_path exists and is replaced (when exists_ok is true), then the replacement is atomic on Unix and Mac OS, but not necessarily atomic on Windows.

If recur is true and if path refers to a directory, then each file and directory within path is recursively deleted before attempting to delete path itself. When a link that refers to a directory is deleted, then the directory content is not deleted through the link, even when recur is true.

If must_exist is #true and path does not refer to a file, directory, or link, then an exception is thrown.

When mode is #'any or must_exist is #false, the check for path’s type/existence is not atomic combined with the deletion of path, so an exception can be thrown if a file, directory or link disappears or changes between the check and deletion.

On Windows, a file or link is deleted by first renaming it to a file in the temporary directory reported by system.path(#'temp_dir), and then deleting the file there. That two-step process can succeed in situations when a file might otherwise be locked by an asynchronous background process. If moving the file does not succeed, it is instead deleted in-place. See also filesystem.current_force_delete_permissions.

The permissions argument specifies permissions used for a new created directory on Unix and Mac OS. The given permissions are adjusted based on the current process’s umask. The permissions argument is ignored on Windows.

A filesystem.Temporary object is Closeable, which means that it can be used with Closeable.let. The Closeable.close implementation for filesystem.Temporary deletes the temporary file or directory, recursively deleting content in the case of a temporary directory.

The name of the temporary file is based on the current time and the make_name function. The argument to make_name is a string containing only ASCII digits. The path returns by make_name is added to dir, and if a file, directory, or link with that name exists already, filesystem.make_temporary starts again to try a new file name.

The permissions and replace_permissions arguments apply to the newly created file. When mode as a path, the permissions argument as used as in filesystem.copy. Otherwise, the permissions arguments are used as in Port.Output.open_file or filesystem.make_directory.

fun process_big_data(src :: Path):   Closeable.let tmp = filesystem.make_temporary()   setup(src, tmp.path)   work(tmp.path)   finish(tmp.path) // produces result   // `tmp.path` is deleted on return or on exception

If exists_ok is false, an exception is thrown if dest_path exists already. When exists_ok is true, recur is true, and a directory is copied, then the content of src_path is effectively spliced with any existing directory tree dest_path.

When follow_links is #false, then a link is copied to a new link. Otherwise, the target of the link is copied to the new path.

The permissions argument is used for newly created files and directories. When it is #false, then a new file or directory uses the permissions of the copied files or directory, otherwise permissions is used for both copied files and new directories. On Windows, if permissions is supplied as non-#false, then after copying, dest_path is set to read-only or not depending on whether the 0o2 bit is present in permissions.

The replace_permissions argument is used only on Unix and Mac OS. When a dest_path is created, it is created with permissions or the permissions of src_path; however, the process’s umask may unset bits in the requested permissions. When dest_path already exists (and exists_ok is true), then the permissions of dest_path are initially left as-is. Finally, when replace_permissions is a true value, then the permissions of dest_path are set after the file content is copied (using again permissions or the permissions of src_path) without modification by the process’s umask.

On Windows, the modification time of src_path is transferred to dest_path. When keep_modify_seconds is true, then on Unix and Mac OS, too, the modification time of src_path is transferred to dest_path after copying.

If path cannot be accessed or the modification timestamp cannot be changed, an exception is thrown only if must_exist is #false. Otherwise, #false is reported for an inaccessible timestamp and failure is silently ignored (and #void is still returned) when setting a timestamp fails.

When set_to is provided, the result is #void. Otherwise, the result is an integer when bits is true, or it is a list of distinct symbols when bits is false. A symbol-list result summarizes permissions for the current process’s user and group.

When path refers to a link, the result is the identity of the link when follow_links is #false, otherwise it is the identity of the link target.

If path refers to a link, then the result map describes the target of the link unless follow_links is false.

The filesystem.normalize_path function is equivalent to filesystem.simplify_path(Path.to_absolute_path(path)). Note that normalization does not use Path.normal_case.

On Windows, the path for a link should be simplified syntactically, so that an up-directory indicator removes a preceding path element independent of whether the preceding element itself refers to a link. Beware that relative-paths links require further care.