Common Lisp the Language, 2nd Edition
These functions provide a standard interface to operations provided in some form by most file systems. It may be that some implementations of Common Lisp cannot support them all completely.
[Function]
rename-file file new-name
The specified file is renamed to new-name (which must be a file name). The file may be a string, a pathname, or a stream. If it is an open stream associated with a file, then the stream itself and the file associated with it are affected (if the file system permits).
X3J13 voted in March 1988
(PATHNAME-STREAM)
to specify exactly which streams may be used as pathnames.
See section 23.1.6.
rename-file returns three values if successful. The first value is the new-name with any missing components filled in by performing a merge-pathnames operation using file as the defaults. The second value is the truename of the file before it was renamed. The third value is the truename of the file after it was renamed.
If the renaming operation is not successful, an error is signaled.
It is an error to specify a file name containing a :wild component,
for file to contain a nil component where the file system does
not permit a nil component, or for the result of defaulting missing
components of new-name from file to contain a nil component
where the file system does not permit a nil component.
X3J13 voted in June 1989 (PATHNAME-WILD)
to specify that supplying a wild pathname
as the file argument to rename-file has implementation-dependent consequences;
rename-file might signal an error, for example,
or might rename all files that match the wild pathname.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require rename-file
to accept logical pathnames (see section 23.1.5).
[Function]
delete-file file
The specified file is deleted. The file may be a string, a pathname, or a stream. If it is an open stream associated with a file, then the stream itself and the file associated with it are affected (if the file system permits), in which case the stream may or may not be closed immediately, and the deletion may be immediate or delayed until the stream is explicitly closed, depending on the requirements of the file system.
X3J13 voted in March 1988
(PATHNAME-STREAM)
to specify exactly which streams may be used as pathnames.
See section 23.1.6.
delete-file returns a non-nil value if successful.
It is left to the discretion of the implementation whether an attempt
to delete a non-existent file is considered to be successful.
If the deleting operation is not successful, an error is signaled.
It is an error to specify a file name that contains a :wild component
or one that contains a nil component where the file system does not
permit a nil component.
X3J13 voted in June 1989 (PATHNAME-WILD)
to clarify that supplying a wild pathname
as the file argument to delete-file has implementation-dependent consequences;
delete-file might signal an error, for example,
or might delete all files that match the wild pathname.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require delete-file
to accept logical pathnames (see section 23.1.5).
[Function]
probe-file file
This predicate is false if there is no file named file, and otherwise returns a pathname that is the true name of the file (which may be different from file because of file links, version numbers, or other artifacts of the file system). Note that if the file is an open stream associated with a file, then probe-file cannot return nil but will produce the true name of the associated file. See truename and the :probe value for the :direction argument to open.
This corresponds to the function called probef in MacLisp and Lisp Machine Lisp.
X3J13 voted in March 1988
(PATHNAME-STREAM)
to specify exactly which streams may be used as pathnames.
See section 23.1.6.
X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that probe-file accepts only non-wild pathnames; an error is signaled if wild-pathname-p would be true of the file argument.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require probe-file to accept logical pathnames (see section 23.1.5). However, probe-file never returns a logical pathname.
X3J13 voted in January 1989
(CLOSED-STREAM-OPERATIONS)
to specify that probe-file is unaffected by
whether the first argument, if a stream, is open or closed. If the first
argument is a stream, probe-file behaves as if the function pathname
were applied to the stream and the resulting pathname used instead.
However, X3J13 further commented that the treatment of open streams
may differ considerably from one implementation to another; for example,
in some operating systems open files are written under a temporary or
invisible name and later renamed when closed. In general, programmers writing
code intended to be portable should be very careful when using probe-file.
[Function]
file-write-date file
file can be a file name or a stream that is open to a file. This returns the time at which the file was created or last written as an integer in universal time format (see section 25.4.1), or nil if this cannot be determined.
X3J13 voted in March 1988
(PATHNAME-STREAM)
to specify exactly which streams may be used as pathnames.
See section 23.1.6.
X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that file-write-date accepts only non-wild pathnames; an error is signaled if wild-pathname-p would be true of the file argument.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require file-write-date
to accept logical pathnames (see section 23.1.5).
[Function]
file-author file
file can be a file name or a stream that is open to a file. This returns the name of the author of the file as a string, or nil if this cannot be determined.
X3J13 voted in March 1988
(PATHNAME-STREAM)
to specify exactly which streams may be used as pathnames.
See section 23.1.6.
X3J13 voted in June 1989 (PATHNAME-WILD) to clarify that file-author accepts only non-wild pathnames; an error is signaled if wild-pathname-p would be true of the file argument.
X3J13 voted in June 1989 (PATHNAME-LOGICAL) to require file-author
to accept logical pathnames (see section 23.1.5).
[Function]
file-position file-stream &optional position
file-position returns or sets the current position within a random-access file.
(file-position file-stream) returns a non-negative integer indicating the current position within the file-stream, or nil if this cannot be determined. The file position at the start of a file will be zero. The value returned by file-position increases monotonically as input or output operations are performed. For a character file, performing a single read-char or write-char operation may cause the file position to be increased by more than 1 because of character-set translations (such as translating between the Common Lisp #\Newline character and an external ASCII carriage-return/line-feed sequence) and other aspects of the implementation. For a binary file, every read-byte or write-byte operation increases the file position by 1.
(file-position file-stream position) sets the position within file-stream to be position. The position may be an integer, or :start for the beginning of the stream, or :end for the end of the stream. If the integer is too large or otherwise inappropriate, an error is signaled (the file-length function returns the length beyond which file-position may not access). An integer returned by file-position of one argument should, in general, be acceptable as a second argument for use with the same file. With two arguments, file-position returns t if the repositioning was performed successfully, or nil if it was not (for example, because the file was not random-access).
[Function]
file-length file-stream
file-stream must be a stream that is open to a file. The length of the file is returned as a non-negative integer, or nil if the length cannot be determined. For a binary file, the length is specifically measured in units of the :element-type specified when the file was opened (see open).
[Function]
file-string-length file-stream object
X3J13 voted in June 1989 (MORE-CHARACTER-PROPOSAL) to add
the function file-string-length.
The object must be a string or a character. The function
file-string-length returns a non-negative integer
that is the difference between what the file-position of the
file-stream would be after and before writing the object
to the file-stream, or nil if this
difference cannot be determined. The value returned may
depend on the current state of the file-stream; that is, calling
file-string-length on the same arguments twice may in certain circumstances
produce two different integers.