You are looking at historical revision 34070 of this page. It may differ significantly from its current revision.
Module (chicken file)
This module provides various generic operations on files and directories. For more specific operations, see also Module (chicken file posix).
All errors related to failing file-operations will signal a condition of kind (exn i/o file).
Basic file operations
create-directory
[procedure] (create-directory NAME #!optional PARENTS?)Creates a directory with the pathname NAME. If the PARENTS? argument is given and not false, any nonexistent parent directories are also created.
Notice that if NAME exists, create-directory won't try to create it and will return NAME (i.e., it won't raise an error when given a NAME that already exists).
file-copy
[procedure] (file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)Copies ORIGFILE (a string denoting some filename) to NEWFILE, BLOCKSIZE bytes at a time. BLOCKSIZE defaults to 1024, and must be a positive integer. Returns the number of bytes copied on success, or errors on failure. CLOBBER determines the behaviour of file-copy when NEWFILE is already extant. When set to #f (default), an error is signalled. When set to any other value, NEWFILE is overwritten. file-copy will work across filesystems and devices and is not platform-dependent.
file-move
[procedure] (file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)Moves ORIGFILE (a string denoting some filename) to NEWFILE, with the same semantics as file-copy, above. file-move is safe across filesystems and devices (unlike rename-file). It is possible for an error to be signalled despite partial success if NEWFILE could be created and fully written but removing ORIGFILE fails.
delete-file
[procedure] (delete-file STRING)Deletes the file with the pathname STRING. If the file does not exist, an error is signaled.
delete-file*
[procedure] (delete-file* STRING)If the file with pathname STRING exists, it is deleted and #t is returned. If the file does not exist, nothing happens and #f is returned.
delete-directory
[procedure] (delete-directory NAME [RECURSIVE])Deletes the directory with the pathname NAME. If RECURSIVE is not given or false, then the directory has to be empty.
directory
[procedure] (directory [PATHNAME [SHOW-DOTFILES?]])Returns a list with all files that are contained in the directory with the name PATHNAME (which defaults to the value of (current-directory)). Files beginning with . are included only if SHOW-DOTFILES? is given and not #f.
directory-exists?
[procedure] (directory-exists? STRING)Returns STRING if a directory with the given pathname exists, or #f otherwise.
file-exists?
[procedure] (file-exists? STRING)Returns STRING if a file or directory with the given pathname exists, or #f otherwise.
rename-file
[procedure] (rename-file OLD NEW)Renames the file or directory with the pathname OLD to NEW. If the operation does not succeed, an error is signaled.
Temporary files and directories
create-temporary-file
[procedure] (create-temporary-file [EXTENSION])Creates an empty temporary file and returns its pathname. If EXTENSION is not given, then .tmp is used. If the environment variable TMPDIR, TEMP or TMP is set, then the pathname names a file in that directory. If none of the environment variables is given the location of the temporary file defaults to /tmp if it exists or the current-directory
create-temporary-directory
[procedure] (create-temporary-directory)Creates an empty temporary directory and returns its pathname. If the environment variable TMPDIR, TEMP or TMP is set, then the temporary directory is created at that location.
Changing file attributes
change-file-mode
[procedure] (change-file-mode FILENAME MODE)Changes the current file mode of the file named FILENAME to MODE using the chmod() system call. The perm/... variables contain the various permission bits and can be combinded with the bitwise-ior procedure.
change-file-owner
[procedure] (change-file-owner FILENAME UID GID)Changes the owner information of the file named FILENAME to the user- and group-ids UID and GID (which should be exact integers) using the chown() system call.
NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.
Information about files
directory?
[procedure] (directory? FILE)Returns #t if FILE designates a directory. Otherwise, it returns #f. FILE may be a pathname, a file-descriptor or a port object.
file-type
[procedure] (file-type FILE [LINK [ERROR]])Returns the file-type for FILE, which should be a filename, a file-descriptor or a port object. If LINK is given and true, symbolic-links are not followed:
regular-file directory fifo socket symbolic-link character-device block-device
Note that not all types are supported on every platform. If ERROR is given and false, then file-type returns #f if the file does not exist; otherwise, it signals an error.
character-device?
block-device?
socket?
[procedure] (character-device? FILE)[procedure] (block-device? FILE)
[procedure] (socket? FILE)
These procedures return #t if FILE given is of the appropriate type. FILE may be a filename, a file-descriptor or a port object. Note that these operations follow symbolic links. If the file does not exist, #f is returned.
file-read-access?
file-write-access?
file-execute-access?
[procedure] (file-read-access? FILENAME)[procedure] (file-write-access? FILENAME)
[procedure] (file-execute-access? FILENAME)
These procedures return #t if the current user has read, write or execute permissions on the file named FILENAME.
fifo?
[procedure] (fifo? FILE)Returns #t if FILE names a FIFO. FILE may be a filename, a port or a file-descriptor.
NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.
regular-file?
[procedure] (regular-file? FILE)Returns true, if FILE names a regular file (not a directory, socket, etc.) This operation follows symbolic links; use either symbolic-link? or file-type if you need to test for symlinks. FILE may refer to a filename, file descriptor or ports object.
Finding files
find-files
[procedure] (find-files DIRECTORY #!key test action seed limit dotfiles follow-symlinks)Recursively traverses the contents of DIRECTORY (which should be a string) and invokes the procedure action for all files in which the procedure test is true.
test may be a procedure of one argument or an irregex object, regex string or SRE expression that will be matched with a full pathname using irregex-match. test defaults to (constantly #t).
action should be a procedure of two arguments: the currently encountered file and the result of the previous invocation of action, or, if this is the first invocation, the value of seed. action defaults to cons, seed defaults to ().
limit should be a procedure of one argument that is called for each nested directory and which should return true, if that directory is to be traversed recursively. limit may also be an exact integer that gives the maximum recursion depth. For example, a depth of 0 means that only files in the top-level, specified directory are to be traversed. In this case, all nested directories are ignored. limit may also be #f (the default), which is equivalent to (constantly #t).
If dotfiles is given and true, then files starting with a "." character will not be ignored (but note that "." and ".." are always ignored). if follow-symlinks is given and true, then the traversal of a symbolic link that points to a directory will recursively traverse the latter. By default, symbolic links are not followed.
Note that action is called with the full pathname of each file, including the directory prefix.
glob
[procedure] (glob PATTERN1 ...)Returns a list of the pathnames of all existing files matching PATTERN1 ..., which should be strings containing the usual file-patterns (with * matching zero or more characters and ? matching zero or one character).
Symbolic links
symbolic-link?
[procedure] (symbolic-link? FILE)Returns true, if FILE names a symbolic link. If no such file exists, #f is returned. This operation does not follow symbolic links itself. FILE could be a filename, file descriptor or port object.
create-symbolic-link
[procedure] (create-symbolic-link OLDNAME NEWNAME)Creates a symbolic link with the filename NEWNAME that points to the file named OLDNAME.
NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.
read-symbolic-link
[procedure] (read-symbolic-link FILENAME [CANONICALIZE])Returns the filename to which the symbolic link FILENAME points. If CANONICALIZE is given and true, then symbolic links are resolved repeatedly until the result is not a link.
NOTE: On native Windows builds (all except cygwin), this procedure is unimplemented and will raise an error.
Previous: Module (chicken errno)