Common Lisp the Language, 2nd Edition


next up previous contents index
Next: Loading Files Up: File System Interface Previous: Opening and Closing

23.3. Renaming, Deleting, and Other File Operations

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).

change_begin
X3J13 voted in March 1988 (PATHNAME-STREAM)   to specify exactly which streams may be used as pathnames. See section 23.1.6.
change_end

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.

old_change_begin
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.
old_change_end

change_begin
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).
change_end


Compatibility note: This corresponds to the function called renamef in MacLisp and Lisp Machine Lisp. The name renamef is not used in Common Lisp because the convention that a trailing f means ``file'' conflicts with the use of a trailing f for forms related to setf.


[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.

change_begin
X3J13 voted in March 1988 (PATHNAME-STREAM)   to specify exactly which streams may be used as pathnames. See section 23.1.6.
change_end

old_change_begin
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.
old_change_end

change_begin
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).
change_end


Compatibility note: This corresponds to the function called deletef in MacLisp and Lisp Machine Lisp.


[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.

change_begin
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.
change_end


[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.

change_begin
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).
change_end


[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.

change_begin
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).
change_end


[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).


Implementation note: Implementations that have character files represented as a sequence of records of bounded size might choose to encode the file position as, for example, record-number*256+character-within-record. This is a valid encoding because it increases monotonically as each character is read or written, though not necessarily by 1 at each step. An integer might then be considered ``inappropriate'' as a second argument to file-position if, when decoded into record number and character number, it turned out that the specified record was too short for the specified character number.
Compatibility note: This corresponds to the function called filepos in MacLisp and Lisp Machine Lisp.


[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).


Compatibility note: This corresponds to the function called lengthf in MacLisp and Lisp Machine Lisp.

change_begin

[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.
change_end



next up previous contents index
Next: Loading Files Up: File System Interface Previous: Opening and Closing


AI.Repository@cs.cmu.edu